La méthode 2 consiste à utiliser la
classe d'aide WrapperStartStopApp.
Cette méthode permet d'intégrer des applications comme Tomcat,
qui sont démarrées à l'aide d'une classe puis arrêtées à l'aide d'une autre classe.
Généralement, ce type d'application ouvre un socket serveur au démarrage
dont le rôle est d'attendre une connexion déclenchant l'arrêt.
La classe d'arrêt, ou classe « stop »,
déclenche l'arrêt en se connectant à l'application lorsqu'elle est lancée.
Le Wrapper fonctionne avec ce type d'application en démarrant l'application,
comme dans la méthode 1, à l'aide de la classe « start »
puis en appelant la méthode main de la classe « stop »
lorsque l'application doit être arrêtée.
Lors de l'intégration avec cette méthode 2
(classe d'aide WrapperStartStopApp),
la classe WrapperStartStopApp replace la classe principale d'une application.
Cela donne à la classe WrapperStartStopApp l'occasion
d'initialiser immédiatement le WrapperManager
et d'enregistrer la JVM auprès du Wrapper. La
classe WrapperStartStopApp
gère ensuite toutes les interactions avec le Wrapper ainsi que le cycle de vie d'une application.
Lorsque le Wrapper envoie un message de démarrage à la JVM via
le WrapperManager,
la méthode main de la classe « start » de l'application est appelée.
De même, lorsque le Wrapper envoie un message d'arrêt,
la méthode main de la classe « stop » de l'application est appelée.
Lorsque la classe d'aide WrapperStartStopApp est lancée,
elle doit connaître les noms de classes des
classes « start » et « stop »
ainsi que tous les paramètres à fournir aux méthodes main de chaque classe.
Cela donne une liste de paramètres un peu plus complexe que
celle de la classe d'aide de la méthode 1 (WrapperSimpleApp).
Le premier paramètre passé à la classe WrapperStartStopApp
sera le nom complet de la classe « start ». Il est suivi
du nombre de paramètres de la méthode main de la classe « start » qui
viennent ensuite. Après les paramètres de la classe « start » vient le nom complet
de la classe « stop ». Celui-ci est suivi d'un indicateur TRUE/FALSE qui
indique à la classe WrapperStartStopApp
si elle doit ou non attendre que tous les threads non démons se soient terminés
avant de réellement quitter. Cet indicateur est ensuite suivi du nombre de paramètres
et des paramètres de la classe « stop ». Ne vous inquiétez pas si cela paraît confus
pour le moment. Un exemple détaillé est fourni ci-dessous.
Instructions détaillées
Cette section vous guide à travers une explication détaillée de
la configuration de Tomcat
pour qu'il s'exécute dans le Wrapper.
La plupart des autres applications peuvent être intégrées en suivant les mêmes étapes.
Installer Tomcat
Ce tutoriel commence par une installation propre de
Tomcat.
Nous avons utilisé Tomcat 9.0.0.M13, les étapes exactes peuvent donc légèrement différer
selon la version que vous avez installée. Tomcat a été installé dans
le répertoire /usr/lib,
ce qui donne un répertoire d'accueil Tomcat de
/usr/lib/apache-tomcat-9.0.0.M13.
Installation des fichiers du Wrapper
Quatre répertoires doivent être configurés afin de pouvoir utiliser le Wrapper.
NOTE
Veuillez vous assurer que vous utilisez le Wrapper approprié, ainsi que
les fichiers libwrapper.so qui
ont été compilés pour la plate-forme utilisée. Cela paraît évident,
mais la version Linux du Wrapper ne fonctionnera pas sur Solaris par exemple.
Répertoire bin
Le Wrapper est livré avec un script shell (sh)
qui peut être utilisé pour démarrer et arrêter de manière fiable toute application Java
contrôlée par le Java Service Wrapper.
Tout d'abord, copiez le fichier suivant dans le répertoire
bin de Tomcat (dans les versions plus anciennes du Wrapper, ce fichier s'appelait « sh.script.in ») :
Renommez le fichier de script pour qu'il reflète le nom de l'application.
{TOMCAT_HOME}/bin/tomcat
Ouvrez maintenant le script dans un éditeur.
Nous devons définir les noms long et court
pour indiquer que le script est utilisé pour lancer Tomcat.
Vous verrez deux variables immédiatement après l'en-tête du script.
APP_NAME et APP_LONG_NAME.
Des valeurs suggérées pour ces variables sont indiquées ci-dessous.
Le script ne devrait pas nécessiter de modification supplémentaire.
Cependant, il suppose que
le fichier wrapper.conf
sera situé dans un répertoire conf
(un niveau au-dessus, ../conf/wrapper.conf).
Si vous souhaitez placer le fichier wrapper.conf ailleurs,
la variable WRAPPER_CONF du script
devra être modifiée en conséquence.
NOTE
Important ! Avant de continuer,
veuillez vous assurer que tous les fichiers copiés dans le
répertoire bin
ont leur bit d'exécution activé.
Répertoire lib
Copiez les deux fichiers suivants dans le répertoire bin de Tomcat.
Pour la plupart des applications, nous copions ces fichiers dans le répertoire lib,
cependant Tomcat place tous ses fichiers de chargeur d'amorçage dans le répertoire bin.
Le fichier libwrapper.so est un
fichier de bibliothèque native
requis par la partie du Wrapper qui s'exécute dans la JVM.
Le fichier wrapper.jar contient toutes les classes du Wrapper.
NOTE
Notez que la bibliothèque native suit des conventions de nommage
légèrement différentes sur certaines plates-formes. Les noms possibles incluent :
libwrapper.a,
libwrapper.sl,
libwrapper.so,
libwrapper.dylib,
et libwrapper.jnilib.
Dans tous les cas, le fichier doit être copié sans modifier
l'extension.
Répertoire conf
Le Wrapper nécessite un fichier de configuration « wrapper.conf » pour chaque application.
L'emplacement standard de ce fichier est un répertoire conf dans le répertoire d'accueil de l'application.
Copiez le fichier modèle suivant wrapper.conf.in
dans le répertoire conf de Tomcat.
{WRAPPER_HOME}/src/conf/wrapper.conf.in
Renommez le fichier comme suit.
Veillez à supprimer l'extension .in
afin que le fichier s'appelle wrapper.conf.
Vous devriez maintenant avoir :
{TOMCAT_HOME}/conf/wrapper.conf
Si vous souhaitez déplacer le fichier de configuration wrapper.conf, vous êtes libre
de le faire. Vous devrez modifier les scripts copiés
dans le répertoire bin ci-dessus,
pour refléter le nouvel emplacement.
Si vous utilisez l'édition Standard ou Professional, veuillez également copier {WRAPPER_HOME}/src/conf/wrapper-license-time.conf
sous le nom {TOMCAT_HOME}/conf/wrapper-license.conf. Cela est utile pour des tests rapides.
Vous devrez le remplacer par une licence d'essai ou permanente pour une exécution de plus de 10 minutes.
Répertoire lang
Les éditions Standard et Professional du Wrapper fournissent des packs linguistiques localisés.
Vous pouvez éventuellement copier ces fichiers, le répertoire {WRAPPER_HOME}/lang complet
vers {TOMCAT_HOME}lang.
Répertoire logs
Le fichier de configuration par défaut wrapper.conf
placera un fichier wrapper.log
dans un répertoire logs sous le répertoire d'accueil de l'application.
Tomcat possède déjà un tel répertoire, nous sommes donc prêts.
{TOMCAT_HOME}/logs
Si vous souhaitez placer le fichier wrapper.log à un autre emplacement,
vous devrez modifier le fichier wrapper.conf
et modifier la propriété wrapper.logfile pour refléter le nouvel emplacement.
Localiser la ligne de commande Java de l'application
Avant de pouvoir configurer le Wrapper pour lancer une application,
vous devez connaître la commande Java complète normalement utilisée.
La plupart des applications utilisent un script pour construire la ligne de commande réelle.
Ces scripts ont tendance à devenir assez lourds,
mais en fait, la possibilité d'éviter d'avoir à travailler avec eux est
l'un des avantages de l'utilisation du Wrapper.
Tomcat est lancé par défaut à l'aide d'un script appelé
startup.sh
puis arrêté à l'aide d'un script appelé
shutdown.sh.
Il est lancé en changeant d'abord le répertoire courant vers le
répertoire bin, puis en l'exécutant à partir de là.
Si vous ouvrez startup.sh dans un éditeur,
vous remarquerez après quelques recherches
que Java n'est pas réellement lancé depuis ce script.
C'est plutôt un autre script,
catalina.sh, qui est appelé.
Les scripts de Tomcat sont très avancés et permettent à l'utilisateur
d'effectuer de nombreuses configurations depuis la ligne de commande.
La ligne de commande que nous capturerons et utiliserons avec le Wrapper sera en réalité
un instantané d'une telle configuration.
Cet exemple suppose qu'aucun paramètre n'est passé aux scripts de démarrage
ou d'arrêt lors de leur exécution.
Si vous ouvrez catalina.sh
dans un éditeur et recherchez "start",
vous verrez une section qui répond à la commande « start » vers le bas du fichier.
Il y a alors deux options pour lancer la JVM avec ou sans
Security Manager. Pour rester simple, nous utiliserons la version
sans gestionnaire de sécurité. Les lignes qui nous intéressent ressemblent
à ce qui suit :
La majeure partie du script a pour tâche de collecter des informations spécifiques au système
et de stocker ces informations dans des variables d'environnement.
La ligne ci-dessus développe ensuite toutes les informations collectées
en la commande Java finale qui lance l'application.
En regardant le code source du script,
nous espérons que vous appréciez la complexité et le souhait d'
éviter complètement d'écrire de tels scripts vous-même.
Afin de configurer le Wrapper,
tout ce dont on a réellement besoin est la ligne de commande finale développée.
Plutôt que de parcourir l'intégralité du script et d'essayer de le comprendre,
nous utiliserons une astuce simple pour afficher la ligne de commande finale dans la console.
Modifiez le script catalina.sh
en le changeant comme suit :
Si vous relancez maintenant le script, vous verrez quelque chose comme
ce qui suit dans la console (votre sortie sera entièrement sur une seule ligne) :
Si vous exécutez maintenant le script catalina.sh stop,
vous verrez quelque chose comme ce qui suit dans la console
(votre sortie sera entièrement sur une seule ligne) :
La ligne d'arrêt (stop) et la ligne de commande de démarrage (start) sont presque identiques.
La seule différence est le paramètre passé à la classe principale à la fin.
Les commandes de la partie eval et la redirection pour capturer la sortie console du démarrage
ne sont pas nécessaires lors de l'utilisation du Wrapper, le reste de cet exemple ignorera donc ces parties des commandes.
Le Wrapper gérera également la mise entre guillemets des éléments de la ligne de commande Java qu'il construit.
Il n'est donc pas nécessaire de les reporter dans le fichier de configuration
wrapper.conf ci-dessous.
Modification du fichier « wrapper.conf »
Afin de pouvoir utiliser la ligne de commande Java ci-dessus avec le Wrapper,
nous devons décomposer les composants de la ligne de commande dans un fichier de configuration.
Ouvrez le fichier wrapper.conf
dans un éditeur et effectuez les modifications ci-dessous.
NOTE
Lorsque des propriétés sont mentionnées ci-dessous, des liens vers leurs descriptions sont fournis.
Veuillez prendre le temps de consulter les descriptions de toutes les propriétés
qui sont modifiées.
Dans de nombreux cas, il existe des détails supplémentaires sur leur utilisation qui ne sont pas mentionnés ici.
Exécutable Java
Tout d'abord, extraire l'exécutable Java et attribuer le chemin d'emplacement à la
propriété
wrapper.java.command :
Il est également possible d'utiliser une référence de variable d'environnement si une telle variable est définie pour votre système.
wrapper.java.command=&JAVA_HOME%/bin/java
Arguments Java
Le Java Service Wrapper est conçu pour toujours définir son répertoire d'accueil initial à l'emplacement du binaire wrapper au démarrage.
Cela permet d'utiliser de manière fiable des chemins relatifs dans votre fichier de configuration.
Non seulement cela rend les configurations beaucoup plus faciles à lire, mais cela facilite également le déplacement de l'application entière.
Dans ce cas, nous placerons le binaire wrapper dans le répertoire /Users/example/apache-tomcat-9.0.118/bin.
Tous les chemins seront donc relatifs à cet emplacement.
La plupart des applications fournissent un certain nombre de paramètres à l'exécutable Java lors de son lancement.
Le Wrapper fournit des propriétés spéciales pour configurer des éléments tels que la mémoire,
ainsi que les chemins de classes et de bibliothèques.
Ceux-ci seront traités ci-dessous, cependant tous les autres paramètres sont configurés à l'aide des
séries de propriétés
wrapper.java.additional.<n>
et wrapper.app.property.<n>.
Les propriétés système référencées par les classes système Java doivent être passées sur la ligne de commande en tant que propriétés wrapper.java.additional.<n>.
Mais d'autres propriétés système peuvent éventuellement être configurées en tant que propriétés wrapper.app.property.<n>, ajoutées dans la version 3.5.57.
Cette dernière a l'avantage de les masquer de la ligne de commande du processus pour une meilleure sécurité et simplicité.
Il est également possible de passer des mots de passe obfusqués et des données sensibles avec cette méthode.
La ligne de commande Tomcat comporte plusieurs propriétés de chaque catégorie. Tout d'abord, les propriétés système Java sont définies avec
les propriétés wrapper.java.additional.<n> :
Le Wrapper exige que son wrapper.jar soit spécifié :
wrapper.jarfile=../bin/wrapper.jar
AVERTISSEMENT
La propriété wrapper.jarfile a été introduite dans la version 3.5.55.
Lors de l'utilisation de versions antérieures du Wrapper, il est nécessaire d'inclure wrapper.jar dans le classpath ci-dessous :
Classpath
Vient ensuite le classpath, qui est configuré à l'aide des
propriétés
wrapper.java.classpath.<n>.
Le Wrapper exige que le classpath soit décomposé en ses éléments individuels.
Il est également possible d'utiliser des caractères génériques pour inclure tous les jars d'un répertoire spécifique.
wrapper.java.classpath.1=../bin/*.jar
Classe principale
Le composant suivant de la commande utilisée pour lancer Tomcat est la
classe principale, org.apache.catalina.startup.Bootstrap.
La classe principale exécutée par Java au lancement est spécifiée à l'aide de la
propriété wrapper.java.mainclass.
Comme mentionné ci-dessus, cependant, comme nous utilisons la classe d'aide WrapperStartStopApp
pour démarrer et arrêter Tomcat, nous spécifierons le nom complet de cette classe comme classe principale.
Les classes principales de Tomcat sont ensuite spécifiées comme paramètres d'application ci-dessous.
Les détails complets pour configurer ces propriétés sont disponibles en consultant
wrapper.app.parameter.<n>.
Les paramètres d'application apparaissent dans la ligne de commande Java, directement après la classe principale.
Lorsque nous utilisons la classe d'aide WrapperStartStopApp, de nombreuses informations doivent
être fournies concernant les classes « start » et « stop ».
Ces informations incluent le nom complet de chaque classe, la liste des paramètres passés à leurs méthodes main, et un indicateur indiquant
à la classe d'aide si elle doit ou non attendre que tous les threads non démons se terminent avant de faire quitter la JVM.
Nous expliquerons comme suit comment ces informations sont encodées.
Nous commençons par présenter les valeurs de propriétés pour l'application Tomcat.
Plusieurs commentaires ont déjà été ajoutés ci-dessus, notamment concernant ce que vous pouvez normalement trouver
dans le fichier wrapper.conf.
Il sera facile de comprendre ce que signifie chaque propriété.
Nous suggérons d'ajouter également ces commentaires à votre fichier de configuration wrapper.conf.
# The first application parameter is the name of the class whose main
# method is to be called when the application is launched. The class
# name is followed by the number of parameters to be passed to its main
# method. Then comes the actual parameters.
wrapper.app.parameter.1=org.apache.catalina.startup.Bootstrap
wrapper.app.parameter.2=1
wrapper.app.parameter.3=start
# The start parameters are followed by the name of the class whose main
# method is to be called to stop the application. The stop class name
# is followed by a flag that controls whether or not the Wrapper should
# wait for all non daemon threads to complete before exiting the JVM.
# The flag is followed by the number of parameters to be passed to the
# stop class's main method. Finally comes the actual parameters.
wrapper.app.parameter.4=org.apache.catalina.startup.Bootstrap
wrapper.app.parameter.5=TRUE
wrapper.app.parameter.6=1
wrapper.app.parameter.7=stop
Les noms des classes start et stop devraient maintenant être clairs.
Le premier nombre de paramètres est nécessaire pour localiser la classe stop dans la liste des paramètres.
Le second nombre est là pour la cohérence.
L'indicateur au paramètre n° 5 ci-dessus est utilisé pour contrôler le comportement de la
classe d'aide WrapperStartStopApp lorsqu'elle arrête la JVM.
Lorsque le Wrapper envoie une demande d'arrêt de la JVM, WrapperStartStopApp
répond en appelant la méthode main de la classe « stop » avec les paramètres configurés.
L'indicateur ci-dessus contrôle ce qui se passe lorsque cette méthode main se termine.
Si l'indicateur est FALSE, alors System.exit(0) sera appelé immédiatement.
Lorsque TRUE, WrapperStartStopApp attendra que tous les threads non démons
se soient terminés avant d'appeler System.exit(0).
Ce dernier est le comportement qui produit l'arrêt le plus propre pour Tomcat.
Si TRUE est spécifié, mais qu'un ou plusieurs threads démons ne se terminent pas, le Wrapper tuera de force
la JVM après l'expiration de son délai d'arrêt.
Le délai défini par défaut est de 30 secondes.
Les threads non démons sont comptés en parcourant tous les threads du
système et en comptant ceux dont la méthode isDaemon retourne FALSE.
Malheureusement, ce compte n'atteindra jamais réellement « 0 » (zéro) sur la plupart des JVM
en raison de l'existence de threads système.
Dans la plupart des JVM Oracle HotSpot, il y aura un thread système non démon.
Afin que l'arrêt fonctionne correctement, ce nombre de threads système doit également être correct.
Il peut être défini en définissant une propriété système :
org.tanukisoftware.wrapper.WrapperStartStopApp.systemThreadCount
La valeur par défaut est « 1 thread ».
NOTE
Si la méthode main de la classe stop appelle System.exit depuis son
thread principal, ce thread se retrouvera en pratique en situation d'interblocage du fait de cet appel.
Le Wrapper évite un interblocage en détectant cela et en poursuivant
l'arrêt après 5 secondes. Cela peut toutefois entraîner l'échec de l'arrêt
propre de l'application par elle-même et devrait être évité dans la mesure
du possible.
Ce cas peut être testé en activant la propriété wrapper.debug=TRUE
puis en observant le fichier journal pendant le processus d'arrêt.
Chemin des bibliothèques
Afin d'utiliser le Wrapper, une propriété supplémentaire doit être définie.
Le Wrapper utilise une bibliothèque native pour contrôler les interactions avec le système.
Ce fichier de bibliothèquelibwrapper.so doit être spécifié
dans le chemin des bibliothèques fourni à la JVM.
Tomcat n'a pas de bibliothèques natives propres, mais s'il en avait,
les répertoires où elles se trouvent devraient également être spécifiés.
Le chemin des bibliothèques est défini à l'aide des
propriétés
wrapper.java.library.path.<n>.
wrapper.java.library.path.1=../bin
Assembler le tout
En rassemblant le tout, nous obtenons ce qui suit :
Il a été signalé que Tomcat 5.0.28 ne fonctionnera pas correctement
si le répertoire bin est inclus dans la propriété système java.endorsed.dirs.
Cela est dû à un changement dans Tomcat, plutôt qu'à un problème avec le Wrapper.
Veuillez modifier la configuration ci-dessus comme suit :
Tomcat peut maintenant être exécuté simplement en exécutant le script
bin/tomcat console.
En raison de la façon dont le Wrapper définit son répertoire courant,
il n'est pas nécessaire d'exécuter ce script depuis le
répertoire bin.
Comme vous le verrez si vous omettez une commande,
les scripts livrés avec le Wrapper sont des scripts de démon assez standard.
Ils acceptent les commandes
console,
start,
stop,
restart et
dump.
Les commandes start,
stop et
restart
sont communes à la plupart des scripts de démon et sont utilisées pour contrôler le Wrapper et son application en tant que processus démon.
La commande status
peut être utilisée pour savoir si le Wrapper est actuellement en cours d'exécution.
La commande console
lancera le Wrapper dans le shell courant,
permettant de tuer l'application avec CTRL-C.
La dernière commande, dump,
enverra un signal « kill -3 » au Wrapper
provoquant un vidage complet des threads de sa JVM.
Félicitations. Votre application devrait maintenant être opérationnelle.
Si vous rencontrez des problèmes, veuillez consulter la
section Dépannage
pour obtenir de l'aide afin d'identifier le problème.
Avancé
Réglage du démarrage
Par défaut, la
classe
WrapperStartStopApp
attendra 2 secondes que la méthode main de l'application utilisateur se termine.
Ensuite,
elle suppose que l'application a démarré et le signale au processus Wrapper.
Cela est fait car de nombreuses applications utilisateur sont écrites avec des méthodes main
qui ne se terminent pas pendant toute la durée de vie de l'application.
Dans de tels cas, il n'existe aucun moyen fiable pour la
classe WrapperStartStopApp de savoir
quand et si l'application a terminé son démarrage.
Si, cependant, on sait que la méthode main de l'application se terminera
une fois l'application démarrée,
il serait idéal que le Wrapper attende qu'elle l'ait fait avant de continuer.
Propriété système waitForStartMain :
Pour les méthodes main qui se terminent de cette façon, le
WrapperStartStopApp
recherche la propriété système
org.tanukisoftware.wrapper.WrapperStartStopApp.waitForStartMain.
Si elle est définie à TRUE,
le WrapperStartStopApp
attendra indéfiniment que la méthode main se termine.
Attendre indéfiniment est une option avantageuse
s'il est certain que la méthode main se terminera en temps voulu.
Mais d'un autre côté, pendant qu'il attend éternellement,
le Wrapper n'abandonnera jamais le processus de démarrage, quelle que soit la durée.
Donc, s'il y a une chance que ce démarrage puisse se bloquer, alors
la propriété système org.tanukisoftware.wrapper.WrapperStartStopApp.maxStartMainWait
pour définir le temps d'attente maximal peut être une meilleure option.
Par exemple, pour attendre jusqu'à 5 minutes (300 secondes) que la méthode main de démarrage se termine,
définissez la propriété à 300 comme suit :
Les méthodes main de nombreuses applications sont conçues pour ne pas se terminer.
Dans ces cas, vous devez soit conserver le délai de démarrage par défaut de 2 secondes,
soit spécifier un délai légèrement plus long, à l'aide de la
propriété maxStartMainWait,
pour simuler le temps que prend votre application pour démarrer.
AVERTISSEMENT
Si « TRUE » est spécifié pour waitForStartMain pour une application
dont la méthode start ne se termine jamais, le Wrapper semblera d'abord fonctionner correctement.
Cependant, le Wrapper est en réalité dans un état d'attente éternel et n'entrera jamais dans un état d'exécution où il peut surveiller votre application.