La Méthode 1 consiste à utiliser la classe d'aide WrapperSimpleApp pour lancer l'application.
C'est de loin le moyen le plus simple de s'intégrer au Wrapper et, lorsque c'est possible, il est fortement recommandé.
Il y a cependant quelques points à connaître lors de l'utilisation de cette méthode.
Lorsque le Wrapper arrête la JVM, il n'y a pas d'appel direct à une application lui demandant de s'arrêter proprement.
Le Wrapper quitte plutôt la JVM en appelant System.exit() depuis l'intérieur de la JVM.
Si l'application a enregistré son propre Shutdown Hook, celui-ci sera invoqué, donnant à l'application une chance de s'arrêter proprement.
Si, en revanche, un Shutdown Hook n'est pas
enregistré, alors l'application se terminera soudainement, comme lors de l'appui sur CTRL-C dans la console (fenêtre de commande).
Les deux cas, avec et sans Shutdown Hook, offrent exactement le même comportement que si l'application s'exécutait sans le Wrapper.
Lors de l'intégration avec cette Méthode 1, la classe d'aide WrapperSimpleApp remplace la classe principale d'une application.
Cela donne à la classe WrapperSimpleApp l'occasion d'initialiser immédiatement
le WrapperManager et d'enregistrer la JVM auprès du Wrapper.
La classe WrapperSimpleApp gère ensuite toute l'interaction 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 principale réelle de l'application est appelée.
La classe d'aide WrapperSimpleApp est informée de la façon de lancer l'application en passant le nom de la
classe principale de l'application, suivi de tout paramètre d'application supplémentaire, à la méthode main de WrapperSimpleApp.
Instructions détaillées
Cette section vous guide à travers une explication détaillée de la façon de configurer
une application HelloWorld simple pour qu'elle s'exécute dans le Wrapper.
La plupart des autres applications peuvent être intégrées en suivant les mêmes étapes.
Application HelloWorld
Ce tutoriel démarrera une application simple HelloWorld qui affiche simplement « Hello world ».
Le chemin vers cette application est /usr/lib/helloworld et sera référencé comme {MYAPP_HOME}.
Certains dossiers supplémentaires (bin, lib, conf et logs) doivent exister, dans lesquels les fichiers du Wrapper seront copiés.
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 les fichiers Wrapper et libwrapper.so
appropriés, qui ont été compilés pour la plateforme utilisée.
Cela semble é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 n'importe quelle application Java
contrôlée par le Java Service Wrapper.
Tout d'abord, copiez le fichier suivant dans le répertoire bin de HelloWorld (dans les versions plus anciennes du Wrapper, ce fichier s'appelait « sh.script.in ») :
Renommez le fichier script pour refléter le nom de l'application.
{MYAPP_HOME}/bin/helloworld
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 HelloWorld.
Vous verrez deux variables immédiatement après l'en-tête du script
APP_NAME et APP_LONG_NAME.
Les valeurs suggérées pour ces variables sont indiquées ci-dessous.
APP_NAME="helloworld"
APP_LONG_NAME="Hello World"
Le script ne devrait pas nécessiter de modification supplémentaire.
Cependant, il suppose que le fichier wrapper.conf
se trouvera 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 dans le 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 la bibliothèque native et le fichier jar du Wrapper dans le répertoire lib de HelloWorld :
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 plateformes. Les noms possibles incluent :
libwrapper.a,
libwrapper.sl,
libwrapper.so
et libwrapper.jnilib.
Dans tous les cas, le fichier doit être copié sans modifier l'extension.
Répertoire conf
Toutes les configurations du Wrapper se font dans
wrapper.conf.
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 HelloWorld.
{WRAPPER_HOME}/src/conf/wrapper.conf.in
Veillez à supprimer l'extension .in afin que
le fichier s'appelle wrapper.conf.
Vous devriez maintenant avoir :
{MYAPP_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.
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.
Assurez-vous d'avoir créé le répertoire :
{MYAPP_HOME}/logs
Si vous souhaitez placer le fichier wrapper.log à un autre emplacement,
vous devrez modifier le fichier wrapper.conf
et changer la propriété wrapper.logfile
pour refléter le nouvel emplacement.
Répertoire lang
À partir de la version 3.5.0 du Wrapper,
le Wrapper peut être localisé.
Les fichiers de ressources linguistiques se trouvent dans le
répertoire lang.
Si nécessaire, créez un répertoire lang sous le
répertoire d'accueil de l'application et copiez-y ces fichiers :
Si vous souhaitez placer les fichiers de ressources linguistiques *.mo à un autre emplacement,
vous devrez modifier le fichier wrapper.conf
et changer la propriété wrapper.lang.folder 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
pour lancer l'application.
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 du Wrapper.
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, puis d'exécuter la commande Java.
Pour configurer le Wrapper, tout ce dont on a réellement besoin est la ligne de commande Java finale.
Dans le cas de notre application HelloWorld simple, un script n'est pas nécessaire. La commande
pour la lancer ressemblerait à ceci :
java com.tanukisoftware.HelloWorld
Une commande plus complexe pour lancer une application Java ressemblerait à ceci :
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.
Variable d'environnement :
Afin de faciliter la configuration, il est recommandé de stocker le répertoire HOME de HelloWorld et de Java
dans une variable d'environnement dans le fichier de configuration.
Cela rendra le fichier conf beaucoup plus lisible et éventuellement plus facile à maintenir si un chemin de répertoire est modifié.
Si elles sont définies dans le fichier de configuration, le Wrapper définira les variables d'environnement à chaque lancement :
Tout d'abord, extraire l'exécutable Java et assigner le chemin d'emplacement à la
propriété wrapper.java.command :
wrapper.java.command=%JAVA_HOME%/bin/java
Arguments Java
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 ; toutefois, tous les autres paramètres sont configurés à l'aide de la
série de propriétés wrapper.java.additional.<n>.
L'application HelloWorld prend 2 arguments Java supplémentaires.
La taille de mémoire initiale et maximale de la JVM spécifiée par -Xms128M (initiale) et -Xmx512M (maximale)
peut également être définie à l'aide des propriétés wrapper.java.initmemory et
wrapper.java.maxmemory.
# Initial Java Heap Size (in MB)
wrapper.java.initmemory=128
# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=512
Jar du Wrapper
Le Wrapper exige que son wrapper.jar soit spécifié :
wrapper.jarfile=%MYAPP_HOME%/lib/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 :
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
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.
Afin d'établir une communication entre HelloWorld et le Wrapper,
l'utilisation de la classe d'aide WrapperSimpleApp
comme classe principale est nécessaire.
La classe principale exécutée par Java au lancement est spécifiée à l'aide de la
propriété wrapper.java.mainclass.
La classe principale de HelloWorld est ensuite spécifiée comme premier paramètre d'application (voir la section ci-dessous).
Les paramètres d'application sont définis à l'aide des
propriétés wrapper.app.parameter.<n>.
Les paramètres d'application apparaissent dans la ligne de commande Java directement après la classe principale.
Comme mentionné ci-dessus, il est nécessaire de définir le premier paramètre comme la classe principale de HelloWorld. Tous les autres
paramètres viennent ensuite.
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.
En rassemblant le tout, nous obtenons ce qui suit :
set.MYAPP_HOME=/usr/lib/helloworld
set.JAVA_HOME=/usr/lib/jvm/java-8-openjdk
wrapper.java.command=%JAVA_HOME%/bin/java
# Java Main class.
wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperSimpleApp
# Wrapper Jar
wrapper.jarfile=%MYAPP_HOME%/lib/wrapper.jar
# Java Classpath
wrapper.java.classpath.1=%MYAPP_HOME%/bin/myjar.jar
# Java Library Path (location of Wrapper.DLL or libwrapper.so)
wrapper.java.library.path.1=%MYAPP_HOME%/lib
# Java Bits. On applicable platforms, tells the JVM to run in 32 or 64-bit mode.
wrapper.java.additional.auto_bits=TRUE
# JVM settings
wrapper.java.additional.1=-Xms128M
wrapper.java.additional.2=-Xmx512M
# Initial Java Heap Size (in MB)
#wrapper.java.initmemory=128
# Maximum Java Heap Size (in MB)
#wrapper.java.maxmemory=512
# Application parameters. Add parameters as needed starting from 1
wrapper.app.parameter.1=com.tanukisoftware.HelloWorld
wrapper.app.parameter.2=arg1
wrapper.app.parameter.3=arg2
Essai
HelloWorld peut maintenant être exécuté simplement en lançant le script bin/helloworld 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 Daemon assez standard.
Ils acceptent les commandes console, start, stop,
restart et dump.
Les commandes start, stop et restart
sont communes à la plupart des scripts Daemon et sont utilisées pour contrôler le Wrapper et son application en tant que processus Daemon.
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 dump complet des threads de sa JVM.
Félicitations. Votre application devrait maintenant être opérationnelle.
Si vous avez rencontré 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 WrapperSimpleApp
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 dû au fait 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'existe aucun moyen fiable pour la classe WrapperSimpleApp de savoir
quand et si l'application a terminé son démarrage.
Si, toutefois, 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 que cela se produise avant de continuer.
Propriété système waitForStartMain :
Pour les méthodes main qui retournent de cette façon, WrapperSimpleApp recherche la
propriété système org.tanukisoftware.wrapper.WrapperSimpleApp.waitForStartMain.
Si elle est définie à TRUE, WrapperSimpleApp 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, quelle que soit la durée.
Ainsi, s'il y a une quelconque chance que ce démarrage puisse se bloquer, alors la
propriété système org.tanukisoftware.wrapper.WrapperSimpleApp.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 retourner.
Dans ces cas, vous devez soit conserver le délai d'attente 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 met votre application à démarrer.
AVERTISSEMENT
Si TRUE est spécifié pour waitForStartMain 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 éternel et n'entrera jamais dans un état d'exécution où il peut surveiller votre application.