Le Wrapper est fourni avec un script shell (sh), qui peut être utilisé pour démarrer et arrêter de façon fiable n'importe quelle application Java contrôlée par le Java Service Wrapper.

Tout d'abord, veuillez copier le script shell suivant dans le répertoire bin de votre application (dans les versions antérieures du Wrapper, ce fichier s'appelait 'sh.script.in').

{WRAPPER_HOME}/src/bin/App.sh.in

Renommez le fichier script pour qu'il reflète le nom de votre application. (Remplacez « MyApp » par le nom de votre application tout au long de ce document.)

/usr/lib/myapp/bin/myapp

Ouvrez maintenant le script dans un éditeur :

Il y a plusieurs variables en haut du script qui permettent de configurer le lancement du Wrapper. Chacune d'elles est précédée d'une description expliquant l'utilisation et les valeurs possibles. Dans la plupart des cas, vous pouvez commencer avec les valeurs par défaut, puis envisager de modifier certaines variables lorsque le besoin s'en fait sentir.

Depuis la version 3.5.37, le script shell recherche un fichier portant le même nom de base que le script, situé dans le même répertoire, et suffixé d'une extension « .shconf ». Si un tel fichier existe, il sera exécuté, ce qui permet de redéfinir n'importe quelle variable du script shell. Si vous devez personnaliser une variable, il est recommandé de le faire dans le fichier .shconf et de laisser le fichier script dans son état d'origine. Ainsi, toute mise à niveau du Wrapper sera plus simple, car vous n'aurez qu'à remplacer le script sans avoir à fusionner vos modifications.

/usr/lib/myapp/bin/myapp
/usr/lib/myapp/bin/myapp.shconf

Notez que vous devrez toujours remplacer le jeton dans la section « INIT INFO » en haut du script principal :

### BEGIN INIT INFO
# Provides: @app.name@
# Required-Start: $local_fs $network $syslog
# Should-Start: 
# Required-Stop:
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: @app.long.name@
# Description: @app.description@
### END INIT INFO

Parmi les variables du script shell, vous voudrez très probablement au moins modifier APP_NAME et APP_LONG_NAME pour indiquer que le script est utilisé pour lancer votre application. Si APP_NAME n'est pas défini, sa valeur par défaut sera le nom de base du script shell, et si APP_LONG_NAME n'est pas défini, sa valeur par défaut sera celle de APP_NAME.

APP_NAME="myapp"
APP_LONG_NAME="My Application"

Le script suppose que l'exécutable wrapper se trouve dans le même répertoire, et que le fichier wrapper.conf se trouve dans un répertoire conf (un niveau au-dessus, ../conf/wrapper.conf). Si vous souhaitez placer l'un ou l'autre de ces fichiers ailleurs, les variables WRAPPER_CMD et WRAPPER_CONF devront être modifiées en conséquence.

PIDDIR="/var/run"

PIDDIR="./"

Démarrer l'application :

L'application peut maintenant être exécutée simplement en exécutant bin/myapp console. En raison de la façon dont le script du Wrapper définit son répertoire courant, il n'est pas nécessaire d'exécuter ce script depuis le répertoire bin.

/usr/lib/myapp/bin/myapp console
Running My Application...
wrapper  | --> Wrapper Started as Console
wrapper  | Launching a JVM...
jvm 1    | Wrapper (Version 3.x.x)
jvm 1    |

Lors de l'exécution avec la commande console, la sortie de la JVM sera visible dans la console.

Arrêter l'application :

L'application peut être arrêtée en appuyant sur CTRL-C dans la console (fenêtre de commande). Cela amènera le Wrapper à arrêter l'application proprement.

Scripts démon standard :

Comme vous le constaterez si vous omettez une commande, les scripts fournis avec le Wrapper sont des scripts démon assez standard. Ils acceptent les commandes console, start, stop, restart, status et dump.

• Les commandes start, stop et restart sont communes à la plupart des scripts 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, ce qui permet d'arrêter l'application avec CTRL-C.
• La dernière commande, dump, enverra un signal « kill -3 » au Wrapper, ce qui amènera la JVM à effectuer un dump complet des threads.

L'application peut être exécutée en tant que processus démon détaché en exécutant le script avec la commande start.

/usr/lib/myapp/bin/myapp start
Running My Application...

Lors de l'exécution avec la commande start, la sortie de la JVM ne sera visible qu'en consultant le fichier wrapper.log à l'aide de tail -f wrapper.log.

Comme l'application s'exécute en tant que processus détaché, elle ne peut pas être arrêtée à l'aide de CTRL-C et continuera de s'exécuter même si la console est fermée.

Pour arrêter l'application, relancez le script avec la commande stop.

/usr/lib/myapp/bin/myapp stop
Stopping TestWrapper Example Application...
Stopped TestWrapper Example Application.

Introduit dans la version 3.4.0 du Wrapper, le script shell fournit un moyen unifié d'installer le Wrapper en tant que démon sur différentes plates-formes (distributions Linux ou autres systèmes Unix), permettant à votre application de démarrer automatiquement au démarrage ou au redémarrage du système.

sudo bin/testwrapper install
[sudo] password for tanuki: 
Detected Ubuntu:
 Installing service testwrapper from current directory /home/tanuki/wrapper/bin
 Adding system startup for /etc/init.d/testwrapper ...
   /etc/rc0.d/K20testwrapper -> ../init.d/testwrapper
   /etc/rc1.d/K20testwrapper -> ../init.d/testwrapper
   /etc/rc6.d/K20testwrapper -> ../init.d/testwrapper
   /etc/rc2.d/S20testwrapper -> ../init.d/testwrapper
   /etc/rc3.d/S20testwrapper -> ../init.d/testwrapper
   /etc/rc4.d/S20testwrapper -> ../init.d/testwrapper
   /etc/rc5.d/S20testwrapper -> ../init.d/testwrapper

Lors de l'étape d'installation, le script détectera automatiquement le système d'exploitation (distributions Linux ou autres plates-formes Unix), puis déterminera quels outils de gestion des services (tels que Systemd, Upstart, Initd) sont présents. Lorsque plusieurs gestionnaires de services sont disponibles, le plus avancé sera choisi. Par exemple, sous Linux, systemd est préféré à upstart, lui-même préféré à initd. Ce comportement par défaut a été introduit dans la version 3.5.31 et peut être modifié en éditant la ligne suivante située près du haut du script :

SERVICE_MANAGEMENT_TOOL=auto

Par exemple, si vous souhaitez forcer l'utilisation d'initd plutôt que Systemd ou Upstart, vous pouvez utiliser ce qui suit :

SERVICE_MANAGEMENT_TOOL=initd

Pour les utilisateurs de FreeBSD et de MacOSX, ou lors de l'utilisation de Systemd ou Upstart sous Linux, la commande install créera un fichier de configuration par défaut décrivant comment la gestion des services du système d'exploitation traitera le script pendant le processus de démarrage.

Il est possible de personnaliser cette étape simplement en plaçant le fichier de configuration dans le répertoire bin :

• Sous MacOSX, le nom de ce fichier doit être {nom de fichier de votre script}.plist.
• Sous FreeBSD ou pour Upstart sous Linux : {nom de fichier de votre script}.install.
• Pour Systemd : {nom de fichier de votre script}.service.

Par exemple, si le script s'appelle « testwrapper », il recherchera « testwrapper.plist » sous MacOSX, « testwrapper.install » sous FreeBSD ou Upstart, et « testwrapper.service » sous Systemd.

Si vous souhaitez désinstaller/supprimer le Wrapper de l'initialisation du système, exécutez le script (en tant qu'utilisateur root !) en passant le paramètre d'action « remove ». Cela arrêtera d'abord l'application Wrapper en cours d'exécution, puis se retirera de l'initialisation.

sudo bin/testwrapper remove
[sudo] password for tanuki: 
Stopping TestWrapper Example Application...
Stopped TestWrapper Example Application.
Detected Ubuntu:
 Removing service testwrapper from current directory /home/tanuki/wrapper/bin
 Removing any system startup links for /etc/init.d/testwrapper ...
   /etc/rc0.d/K20testwrapper
   /etc/rc1.d/K20testwrapper
   /etc/rc2.d/S20testwrapper
   /etc/rc3.d/S20testwrapper
   /etc/rc4.d/S20testwrapper
   /etc/rc5.d/S20testwrapper
   /etc/rc6.d/K20testwrapper

L'installation des versions du Wrapper antérieures à 3.4.0 doit être effectuée manuellement. Si votre plate-forme n'est pas incluse, veuillez parcourir celles qui l'ont été et les adapter si nécessaire. Veuillez publier vos adaptations sur la liste de diffusion wrapper-user@lists.sourceforge.net et nous serons ravis de les inclure dans la prochaine version.

• Démarrage au redémarrage (Debian Linux)

• Démarrage au redémarrage (Solaris) BROUILLON

Si l'exécutable wrapper est lancé sans aucun paramètre ou avec un « -? », la sortie d'utilisation suivante s'affichera.

Java Service Wrapper Professional Edition 64-bit {version}
  Copyright (C) 1999-{year} Tanuki Software, Ltd. All Rights Reserved.
    https://wrapper.tanukisoftware.com

Usage:
  ./wrapper <command> <configuration file> [configuration properties] [...]
  ./wrapper <configuration file> [configuration properties] [...]
     (<command> implicitly '-c')
  ./wrapper <command>
     (<configuration file> implicitly 'wrapper.conf')
  ./wrapper
     (<command> implicitly '-c' and <configuration file> 'wrapper.conf')

where <command> can be one of:
  -c  --console run as a Console application
  -h  --hostid  print a list of HostIds which can be used to license this host.
  -v  --version print the Wrapper's Version information
  -?  --help    print this help message
  -- <args>     mark the end of Wrapper arguments.  All arguments after the
                '--' will be passed through unmodified to the java application.

<configuration file> is the conf file to use.  Filename must be absolute or
  relative to the location of ./wrapper

[configuration properties] are configuration name-value pairs which override values
  in the Wrapper configuration file.  For example:
  wrapper.debug=true

  --cipher Obfuscate a password and generate a token along with wrapper.cipher.*
    properties that can then be used in the configuration file for added safety.
    The value to be encoded can be piped to Stdin of the Wrapper.  Otherwise, it
    will be prompted.
    The following arguments are available:
      --method <method name> One of the following methods:
          base64   : to encode in Base64
          base64url: to encode in the modified Base64 for URLs
          obf      : to generate a fixed obfuscated string
          robf     : to generate a random obfuscated string
      --name <cipher name> Optional cipher name. This argument is required when
        '--private_keyfile' is specified.
      --private_keyfile <file path> Optional path to a private key file
        (available for method 'obf' and 'robf').
      --encoding <utf8 or utf-8> Encoding to use when reading Stdin.
      --echo Echo the input to debug encoding issues (do not use with real
        passwords).
      --simple If specified, the output will only contain the obfuscated string.

  --keygen Generate a private key file to be used when obfuscating passwords.
    The following arguments are available:
      --method <method name> Obfuscation method for which the private key is
        intended to be used:
          obf : to generate a key for fixed obfuscation
          robf: to generate a key for random obfuscation
      --private_keyfile <file path> Specifies the filename of the key file.

  Please note that any file references must be absolute or relative to the location
  of the Wrapper executable.

Pour exécuter le Wrapper dans un shell, veuillez utiliser la commande -c, suivie du chemin vers le fichier wrapper.conf. L'emplacement du fichier wrapper.conf peut être absolu ou relatif. Si un chemin relatif est utilisé, le chemin est toujours relatif à l'emplacement du fichier wrapper, et non au répertoire courant.

/usr/lib/myapp/bin/wrapper -c ../conf/wrapper.conf

Pour lancer l'application en tant que processus démon depuis la ligne de commande, veuillez ajouter wrapper.daemonize=TRUE après le chemin vers le fichier wrapper.conf. Cependant, l'utilisation du script shell est recommandée.

/usr/lib/myapp/bin/wrapper -c ../conf/wrapper.conf wrapper.daemonize=TRUE