La Méthode 2 consiste à utiliser la classe d'assistance WrapperStartStopApp.
Cette méthode offre un moyen 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.
Typiquement, 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 stop class
déclenche l'arrêt en se connectant à l'application lors de son lancement.
Le Wrapper fonctionne avec ce type d'application en démarrant l'application, comme dans la Méthode 1, à l'aide de la
start class puis en appelant la méthode main de la
stop class lorsqu'il est temps d'arrêter l'application.
Lors de l'intégration avec cette Méthode 2, la classe d'assistance WrapperStartStopApp remplace 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'assistance WrapperStartStopApp est lancée, elle doit être informée des
noms de classes de la classe start et de la classe stop,
ainsi que de 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'assistance 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 d'un nombre indiquant le nombre de paramètres de la méthode main de la classe start, qui viendront 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 indiquant à la classe WrapperStartStopApp
si elle doit ou non attendre que tous les threads non démons se soient terminés avant de quitter réellement.
Cet indicateur est ensuite suivi du nombre de paramètres de la classe stop et des paramètres.
Ne vous inquiétez pas si cela vous paraît confus pour le moment.
Un exemple détaillé est fourni ci-dessous.
Instructions détaillées
Cette section vous guidera à 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 commencera avec 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 racine, D:\,
ce qui donne un répertoire home de Tomcat de D:\apache-tomcat-9.0.0.M13.
Installation des fichiers du Wrapper
Quatre répertoires doivent être configurés afin de pouvoir utiliser le Wrapper.
répertoire bin
Tout d'abord, copiez les fichiers suivants dans le répertoire bin de Tomcat :
Renommez les trois fichiers batch pour qu'ils reflètent le nom de votre application, comme suit.
Veillez à supprimer les extensions .in afin que tous les fichiers se terminent par .bat.
(Selon la configuration de l'explorateur de fichiers de votre ordinateur, vous pourriez ne pas voir les extensions de fichiers.)
Le fichier wrapper.exe est l'exécutable réel du Wrapper.
Les trois fichiers batch sont utilisés pour exécuter Tomcat dans une console, et pour l'installer et le désinstaller en tant que service Windows.
Ces fichiers batch ne devraient nécessiter aucune modification.
Ils supposent 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,
alors les trois fichiers batch nécessiteront une modification appropriée.
répertoire lib
Copiez les deux fichiers suivants dans le répertoire lib de Tomcat :
Le fichier wrapper.dll 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.
répertoire conf
Le Wrapper nécessite un fichier de configuration wrapper.conf pour chaque application.
L'emplacement standard de ce fichier est dans un répertoire conf du répertoire home 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 fichiers batch copiés dans le répertoire bin ci-dessus pour refléter le nouvel emplacement.
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 home 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 éditer 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 que le Wrapper puisse être configuré pour lancer une application,
vous devrez connaître la commande Java complète qui est normalement utilisée.
La plupart des applications utilisent un fichier batch pour construire la ligne de commande réelle.
Ces fichiers batch ont tendance à devenir assez encombrants,
mais en fait, la possibilité d'éviter d'avoir à travailler avec eux est
l'un des avantages de travailler avec le Wrapper.
Tomcat est lancé par défaut à l'aide d'un fichier batch appelé startup.bat
puis arrêté à l'aide d'un fichier batch appelé shutdown.bat.
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.bat dans un éditeur, vous remarquerez après quelques
investigations que Java n'est pas réellement lancé à partir de ce fichier batch.
C'est plutôt un autre fichier batch, catalina.bat, qui est appelé.
Les scripts de Tomcat sont très avancés et permettent à l'utilisateur
d'effectuer beaucoup de configuration à partir de la ligne de commande.
La ligne de commande que nous allons capturer et utiliser avec le Wrapper sera en réalité un instantané d'une telle configuration.
Cet exemple supposera 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.bat dans un éditeur et faites défiler
jusqu'en bas du fichier, vous verrez quatre lignes qui lancent Java.
Avec les valeurs par défaut que nous utilisons, la première d'entre elles sera utilisée.
La ligne qui nous intéresse ressemble à ce qui suit : (La commande est très longue et a été tronquée.)
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 source du fichier batch,
nous espérons que vous apprécierez la complexité et le désir d'avoir à
é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 lire 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.
Éditez le fichier batch catalina.bat en insérant ECHO au début de la ligne ci-dessus.
Après cela, vous devriez avoir : (Une fois de plus, la ligne a été tronquée pour tenir à l'écran.)
Si vous réexécutez maintenant le fichier batch, vous verrez quelque chose comme ce qui suit
dans la console (votre sortie sera entièrement sur une seule ligne) :
Nous devons maintenant répéter le même processus pour le fichier batch shutdown.bat
ainsi que pour startup.bat ci-dessus.
Vous serez peut-être surpris de constater que si vous l'exécutez simplement maintenant, vous obtiendrez la sortie suivante.
Cela est dû au fait que startup.bat et shutdown.bat appellent
catalina.bat en ne changeant qu'un paramètre.
À part le start Tomcat au début de la ligne de démarrage, les deux commandes sont presque identiques.
La seule différence est le paramètre passé à la classe principale à la fin.
La portion start Tomcat de la commande n'est utilisée que pour lancer Tomcat dans sa propre console.
Cela n'est pas nécessaire lors de l'utilisation du Wrapper, le reste de cet exemple ignorera donc cette portion de la commande.
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 d'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 indiquées ci-dessous.
NOTE
Nous avons fourni quelques liens où vous trouverez la description des propriétés mentionnées.
Veuillez prendre le temps de consulter les descriptions de toutes les propriétés qui sont modifiées.
Dans de nombreux cas, vous pouvez y trouver des détails complets 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
wrapper.java.command=D:\jdk1.8.0_45\bin\java
Arguments Java
La plupart des applications fournissent un certain nombre de paramètres à l'exécutable Java lors de son lancement.
Le Java Service Wrapper fournit des propriétés spéciales pour configurer des éléments comme 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 de la
série de propriétés wrapper.java.additional.<n>.
La ligne de commande de Tomcat possède plusieurs de ces propriétés :
wrapper.java.additional.1=-Dcatalina.base=D:\apache-tomcat-9.0.0.M13
wrapper.java.additional.2=-Dcatalina.home=D:\apache-tomcat-9.0.0.M13
wrapper.java.additional.3=-Djava.io.tmpdir=D:\apache-tomcat-9.0.0.M13\temp
wrapper.java.additional.4=-Djdk.tls.ephemeralDHKeySize=2048
wrapper.java.additional.5=-Djava.protocol.handler.pkgs=org.apache.catalina.webresources
# Following properties are optional:
wrapper.java.additional.6=-Djava.util.logging.config.file=D:\apache-tomcat-9.0.0.M13\conf\logging.properties
wrapper.java.additional.7=-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
Notez que tous les guillemets ont été supprimés car aucun de ces chemins ne contiendra jamais de guillemets.
Consultez la documentation des propriétés pour savoir comment gérer les propriétés contenant des espaces.
Jar du Wrapper
Le Wrapper nécessite que son wrapper.jar soit spécifié :
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 :
Ensuite, les indices des éléments de classpath suivants doivent être ajustés afin que la propriété wrapper.java.classpath.1 ne soit pas répétée.
Classpath
Nous avons maintenant 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.
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 lors du lancement est spécifiée à l'aide de la
propriété wrapper.java.mainclass.
Comme mentionné ci-dessus cependant, parce que nous utilisons la classe d'assistance 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 visitant la
page de la propriété 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'assistance WrapperStartStopApp, de nombreuses informations doivent
être fournies concernant à la fois les classes start et stop.
Ces informations comprennent le nom complet de chaque classe, la liste des paramètres passés à leurs méthodes main, et un indicateur indiquant
à la classe d'assistance si elle doit ou non attendre que tous les threads non démons se terminent avant de faire quitter la JVM.
Nous expliquerons comment ces informations sont encodées comme suit.
Nous commençons par présenter les valeurs des propriétés pour l'application Tomcat.
Plusieurs commentaires ont déjà été ajoutés ci-dessus, spécifiquement sur ce que vous pouvez normalement trouver
dans le fichier wrapper.conf.
Il sera facile de comprendre ce que chaque propriété signifie.
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 stop class 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'assistance 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 retourne.
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 la 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 bloqué par un deadlock à cause de cet appel.
Le Wrapper évite un deadlock en détectant cela et en poursuivant l'arrêt après 5 secondes.
Cependant, cela peut entraîner l'échec d'un 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.
Ensuite, consultez 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èquewrapper.dll
doit être spécifié dans le chemin des bibliothèques fourni à la JVM.
Tomcat n'a pas de bibliothèques natives qui lui sont propres, mais si c'était le cas,
les répertoires où elles se trouvent devraient également être spécifiés.
Remarquez que, bien que ces configurations fonctionnent correctement sur cette machine particulière,
elles dépendent fortement de la structure des répertoires et de la plateforme.
En tirant parti du fait que le Wrapper définit toujours le répertoire de travail
à l'emplacement du fichier wrapper.exe et également en utilisant une seule variable d'environnement, nous pouvons modifier les propriétés ci-dessus.
De cette façon, elles sont complètement indépendantes de la plateforme et de la machine.
Il a été rapporté 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 causé par un changement dans Tomcat, plutôt que par un problème avec le Wrapper.
Veuillez modifier la configuration ci-dessus comme suit :
La dernière étape consiste à définir les propriétés du service Windows.
Nous définirons uniquement les propriétés qui devraient être changées, mais il en existe plusieurs autres.
Veuillez lire la documentation pour les détails sur leur utilisation.
Les valeurs suggérées pour ces variables sont indiquées ci-dessous.
wrapper.ntservice.name=Tomcat
wrapper.ntservice.displayname=Tomcat Application Server
wrapper.ntservice.description=Tomcat Application Server
Mise à l'essai
Tomcat peut maintenant être exécuté simplement en exécutant le fichier batch bin\Tomcat.bat.
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 fichier batch
depuis le répertoire bin.
Veuillez essayer d'exécuter l'application une fois en tant qu'application console
pour vérifier la configuration avant d'essayer de l'exécuter en tant que service.
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é
Ajustement 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 parce que de nombreuses applications utilisateur sont écrites avec des méthodes main qui ne retournent pas pendant toute la durée de vie de l'application.
Dans de tels cas, il n'y a 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 retournera 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 retournent de cette façon, WrapperStartStopApp recherche la
propriété système org.tanukisoftware.wrapper.WrapperStartStopApp.waitForStartMain.
Si elle est définie à TRUE, 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 retournera en temps voulu.
Mais d'un autre côté, pendant qu'il attend éternellement,
le Wrapper n'abandonnera jamais le processus de démarrage, peu importe le temps que cela prend.
Donc, s'il y a une quelconque 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 maximum 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 retourner.
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 dans waitForStartMain est spécifié pour une application
dont la méthode start ne retourne jamais, le Wrapper semblera d'abord fonctionner correctement.
Cependant, le Wrapper est en réalité dans un état d'attente éternelle et n'entrera jamais dans un état d'exécution, ce qui signifie
que le Gestionnaire de services Windows et plusieurs des mécanismes de récupération d'erreurs du Wrapper ne fonctionneront pas correctement.