Java a la capacité d'enregistrer un thread spécial, appelé hook d'arrêt, qui sera exécuté par la JVM lorsqu'elle est prête à s'arrêter. Sans hook d'arrêt, une application n'aurait aucun moyen de savoir qu'elle est en train d'être arrêtée. Ainsi, elle n'aurait aucun moyen de savoir qu'elle doit terminer tout travail en cours et sauvegarder toutes les données qui doivent être préservées.

Nous n'entrerons pas dans les détails des hooks d'arrêt ici, mais voici un exemple rapide de ce à quoi ils ressemblent et comment les enregistrer auprès de la JVM.

Enregistrer un hook d'arrêt :

Thread shutdownHook = new Thread( "myapp-shutdown-hook" )
    {
        public void run()
        {
            System.out.println( "Starting MyApp shutdown..." );
            // Do some cleanup work.
            System.out.println( "MyApp shutdown complete." );
        }
    };
Runtime.getRuntime().addShutdownHook( shutdownHook );

Il est possible, et courant, d'avoir plusieurs hooks d'arrêt enregistrés. Habituellement, chaque application ou composant majeur enregistrera son propre hook d'arrêt si nécessaire. L'enregistrement des hooks d'arrêt doit être effectué dans le cadre du processus d'initialisation afin qu'un arrêt soit géré correctement, quel que soit son moment. Dans la plupart des cas, vous pouvez enregistrer un hook d'arrêt puis l'oublier.

Supprimer un hook d'arrêt :

Il est généralement possible de coder le hook d'arrêt sans le faire, mais si vous constatez que vous devez supprimer un hook d'arrêt à un moment donné, cela peut se faire comme suit :

Runtime.getRuntime().removeShutdownHook( shutdownHook );

Arrêt de la JVM :

Lorsque la JVM commence à s'arrêter, elle parcourt tous les hooks d'arrêt enregistrés et les lance chacun en tant que nouveau Thread. Ces threads de hooks d'arrêt s'exécutent ensuite en parallèle jusqu'à ce qu'ils soient tous terminés. Lorsque le dernier hook d'arrêt se termine, la JVM se ferme immédiatement, tuant tous les autres threads encore en cours d'exécution.

jvm 1    | Starting MyApp shutdown...
jvm 1    | ...
jvm 1    | MyApp shutdown complete.
wrapper  | <-- Wrapper Stopped

Un problème avec les hooks d'arrêt est qu'ils peuvent potentiellement prendre des heures à se terminer. Pendant ce temps, il n'y a normalement aucun moyen de dire à Java de s'arrêter plus tôt. Le Wrapper contourne ce problème en utilisant le délai de sortie de la JVM configurable, discuté ci-dessous.

Lorsque vous commencez à arrêter la JVM qui a été intégrée avec le Java Service Wrapper, la JVM exécutera le hook d'arrêt interne du Wrapper. Le Wrapper utilise son propre hook d'arrêt pour initier un arrêt propre de l'application encapsulée par le Wrapper, puis pour nettoyer après lui-même.

Si vous êtes comme la plupart des utilisateurs et que vous utilisez la méthode d'intégration n° 1 (WrapperSimpleApp) ou la méthode n° 4 (WrapperJarApp) pour votre application, alors le hook d'arrêt du Wrapper se terminera presque immédiatement.

Cependant, si vous utilisez la méthode d'intégration n° 2 ou la méthode n° 3, alors le hook d'arrêt du Wrapper s'exécutera jusqu'à ce que l'application soit arrêtée. Pour la méthode n° 2 WrapperStartStopApp, c'est lorsque la méthode main de la classe shutdown enregistrée se termine. Pour l'implémentation WrapperListener de la méthode n° 3, c'est lorsque la méthode WrapperListener.stop() se termine.

Le Wrapper définit un délai d'arrêt, qui est le temps maximum qu'il accordera au hook d'arrêt du Wrapper pour se terminer. Si l'arrêt du Wrapper ne signale pas qu'il s'est terminé dans ce délai, alors le Wrapper considérera que le processus d'arrêt est figé et tuera la JVM de force. Cela est fait pour contourner les problèmes d'arrêt qui laisseraient autrement l'application dans un état inutilisable. Le délai d'arrêt est de 30 secondes par défaut et peut être configuré à l'aide de la propriété wrapper.shutdown.timeout.

jvm 1    | Stopping...
wrapper  | Shutdown failed: Timed out waiting for signal from JVM.
wrapper  | JVM did not exit on request, terminated
wrapper  | <-- Wrapper Stopped

Une fois que le hook d'arrêt du Wrapper s'est terminé et que le Wrapper a été notifié que la JVM est prête à s'arrêter, le Wrapper passe dans un mode où il attend simplement que la JVM se termine d'elle-même. Rappelez-vous que la JVM lance tous les hooks d'arrêt enregistrés en parallèle. Elle attendra que le dernier se soit terminé, puis se fermera. Si l'un des autres hooks d'arrêt met longtemps à se terminer, cela peut prendre un certain temps. Comme pour le délai d'arrêt ci-dessus, le Wrapper est conçu pour expirer après un certain temps afin d'éviter de se retrouver dans un état où l'application n'est pas disponible. Ce délai est de 15 secondes par défaut et peut être configuré à l'aide de la propriété wrapper.jvm_exit.timeout.

jvm 1    | Stopping...
jvm 1    | Stopped.
wrapper  | Shutdown failed: Timed out waiting for the JVM to terminate.
wrapper  | JVM did not exit on request, terminated
wrapper  | <-- Wrapper Stopped

Une fois que le dernier des hooks d'arrêt s'est terminé, le processus JVM devrait se terminer presque immédiatement. Une cause connue d'une sortie trop longue est lorsqu'un fichier dump est en cours d'enregistrement alors que le profilage du tas de la JVM a été activé.

Compatibilité :	1.0.0
Éditions :
Plateformes :

La première méthode que vous rencontrerez probablement est simplement d'appuyer sur CTRL-C pendant que le Wrapper s'exécute dans une console ou un terminal. Cette méthode ne nécessite aucun développement particulier et peut être utilisée avec à peu près n'importe quelle application.

Windows :

Lorsque l'utilisateur appuie sur CTRL-C sous Windows, le Wrapper transmet la demande au processus Java. Java gère ensuite la demande en lançant tous les hooks d'arrêt qui ont été enregistrés dans l'application.

...
wrapper  | CTRL-C trapped.  Shutting down.
jvm 1    | Starting MyApp shutdown...
jvm 1    | ...
jvm 1    | MyApp shutdown complete.
wrapper  | <-- Wrapper Stopped

UNIX :

Sur les plateformes UNIX, CTRL-C provoque l'envoi d'un signal INT au Wrapper. Cela fait que la sortie est légèrement différente.

...
wrapper  | INT trapped.  Shutting down.
jvm 1    | Starting MyApp shutdown...
jvm 1    | ...
jvm 1    | MyApp shutdown complete.
wrapper  | <-- Wrapper Stopped

CTRL-C :

Parfois, lorsque vous développez une application, il peut devenir fastidieux d'attendre toujours que l'application s'arrête proprement. Si vous voulez vraiment l'arrêter immédiatement, le Wrapper vous permet d'appuyer une seconde fois sur CTRL-C pour tuer la JVM. Bien que très utile, cela a l'inconvénient que les données pourraient ne pas être sauvegardées correctement car les hooks d'arrêt n'ont pas été exécutés jusqu'au bout.

...
wrapper  | CTRL-C trapped.  Shutting down.
jvm 1    | Starting MyApp shutdown...
wrapper  | CTRL-C trapped.  Forcing immediate shutdown.
wrapper  | JVM did not exit on request, terminated
wrapper  | <-- Wrapper Stopped

Désactiver CTRL-C :

La plupart des utilisateurs apprécient cette fonctionnalité, mais au cas où vous voudriez vous assurer que la JVM a toujours une chance de s'arrêter proprement, vous pouvez désactiver la fonctionnalité d'arrêt immédiat à l'aide de la propriété wrapper.disable_forced_shutdown à partir de la version 3.5.15 du Wrapper.

Il existe également des cas où vous souhaitez intentionnellement empêcher vos utilisateurs d'arrêter l'application avec CTRL-C. Cela peut être facilement réalisé à l'aide de la propriété wrapper.ignore_signals. Veuillez noter que si vous faites cela, vous devrez bien sûr utiliser l'une des autres méthodes pour arrêter l'application.

wrapper  | CTRL-C trapped, but ignored.

Compatibilité :	1.0.0
Éditions :
Plateformes :

Sur les plateformes UNIX, il est également possible d'envoyer un signal TERM au processus Wrapper. C'est en fait ainsi que le script shell fourni avec le Wrapper demande son arrêt par défaut.

Le signal TERM fonctionne presque exactement comme la méthode CTRL-C ci-dessus.

...
wrapper  | TERM trapped.  Shutting down.
jvm 1    | Starting MyApp shutdown...
jvm 1    | ...
jvm 1    | MyApp shutdown complete.
wrapper  | <-- Wrapper Stopped

Vous pouvez envoyer ce signal depuis la ligne de commande à l'aide de la commande suivante.

kill {pid}

Le {pid} doit être replaced par l'identifiant de processus du Wrapper. Si vous souhaitez le faire de manière programmatique, vous pouvez faire en sorte que le Wrapper stocke son identifiant de processus actuel dans un fichier pid à l'aide de la propriété wrapper.pidfile. Si vous utilisez le script shell du Wrapper, ce fichier devrait exister par défaut dans le même répertoire que le binaire du Wrapper.

La propriété wrapper.ignore_signals peut également être utilisée pour désactiver ce type d'arrêt.

wrapper  | TERM trapped, but ignored.

Compatibilité :	1.0.0
Éditions :
Plateformes :

Lors de l'exécution en tant que service Windows, il est possible d'arrêter le service à l'aide de l'une des commandes suivantes :

• Premièrement, arrêtez le service depuis le Panneau de configuration des services ([Panneau de configuration] - [Outils d'administration] - [Services]).
• Deuxièmement, utilisez la commande net depuis la ligne de commande :

net stop myapp

• Et troisièmement, utilisez la commande sc, également depuis la ligne de commande :

sc stop myapp

Dans tous les cas, lorsqu'une commande est émise pour demander l'arrêt d'un service, le Gestionnaire de contrôle des services Windows contrôlera le processus d'arrêt du service, puis rendra compte une fois terminé. Le Wrapper répondra toujours en tentant d'arrêter la JVM proprement.

jvm 1    | ...
jvm 1    | Stopping...
wrapper  | <-- Wrapper Stopped

Lors de l'arrêt de l'ensemble du système, le Wrapper sera arrêté par le système d'exploitation avant l'arrêt. Certaines versions de Windows ignoreront les rapports indiquant que le service s'arrête et tueront simplement le service s'il prend trop de temps. Si cela se produit, vous pourriez voir un fichier journal tronqué, car le Wrapper et sa JVM auront été tués de force par le système d'exploitation.

wrapper  | User logged out.  Ignored.
wrapper  | Machine is shutting down.
jvm 1    | Stopping...
wrapper  | <-- Wrapper Stopped

Compatibilité :	3.1.1
Éditions :
Plateformes :

Le Wrapper peut être configuré pour générer un fichier d'ancrage à l'aide de la propriété wrapper.anchorfile. Une ancre est utilisée par les navires pour les empêcher de dériver. Le Wrapper utilise ce fichier de manière très similaire. Il créera le fichier d'ancrage au démarrage, puis vérifiera périodiquement qu'il existe toujours. Lorsque et si le fichier est jamais supprimé, le Wrapper commencera immédiatement le processus d'arrêt.

jvm 1    | ...
wrapper  | Anchor file deleted.  Shutting down.
wrapper  | <-- Wrapper Stopped

Sous UNIX, si vous avez modifié le script shell pour ignorer les signaux système, il utilisera cette méthode pour contrôler quand le Wrapper doit être arrêté.

Compatibilité :	3.2.0
Éditions :
Plateformes :

Le Wrapper peut être configuré pour rechercher un fichier de commande qui peut contenir l'une des nombreuses commandes que le Wrapper interprétera. L'emplacement de ce fichier peut être spécifié à l'aide de la propriété wrapper.commandfile. Il est désactivé par défaut.

Les commandes sont émises simplement en créant un fichier texte contenant la commande. Le fichier sera supprimé par le Wrapper dès que la commande est traitée.

STOP

jvm 1    | ...
wrapper  | Command 'STOP'. Shutting down with exit code 0.
jvm 1    | Stopping...
wrapper  | <-- Wrapper Stopped

Si cette méthode est utilisée, il est bien sûr important de protéger le répertoire où se trouvera le fichier de commande pour s'assurer que seuls les utilisateurs qui devraient pouvoir émettre des commandes peuvent le faire. Veuillez consulter la documentation de la propriété wrapper.commandfile pour une liste complète des commandes disponibles, ainsi que plusieurs autres exemples.

Compatibilité :	3.0.4
Éditions :
Plateformes :

Le Wrapper est livré avec une classe optionnelle qui vous permet de vous connecter avec n'importe quel client Telnet pour contrôler le Wrapper à distance. L'utilisation de cette méthode nécessite d'ajouter quelques lignes de code à votre application. Veuillez consulter les Javadocs de la classe WrapperActionServer pour une explication complète.

Pour configurer un serveur simple qui n'autorisera le client qu'à arrêter le Wrapper, veuillez essayer d'ajouter le code suivant :

int port = 9999;
WrapperActionServer server = new WrapperActionServer( port );
server.enableShutdownAction( true );
server.start();

Des actions supplémentaires peuvent être activées en appelant les méthodes appropriées listées dans les Javadocs.

Une fois cela configuré, vous pouvez maintenant vous connecter à l'application avec la commande telnet localhost 9999. Une fois connecté, appuyez simplement sur la touche S, et le Wrapper s'arrêtera proprement. Cela peut constituer un risque de sécurité potentiel, alors assurez-vous de protéger ce port s'il est utilisé. Il est également possible de lier le socket d'écoute à localhost, empêchant ainsi les connexions distantes.

Compatibilité :	1.0.0
Éditions :
Plateformes :

En dernier recours, ou dans le cadre de vos tests, vous pourriez souhaiter tuer de force le processus Wrapper. Sous Windows, vous pouvez le faire en ouvrant le Gestionnaire des tâches, en localisant le fichier wrapper.exe dans l'onglet Processus, puis en appuyant sur End Process. Sous UNIX, vous pouvez accomplir la même chose en utilisant une variante de la commande kill, kill -9 {pid}. Dans les deux cas, vous devez faire très attention à ne pas terminer le mauvais processus.

Lorsque vous tuez le processus Wrapper de cette manière, il est immédiatement terminé et n'aura pas la possibilité d'arrêter la JVM proprement. Le Wrapper est conçu de telle sorte que son composant Java commencera automatiquement le processus d'arrêt Java. Cela est essentiel pour éviter que la JVM ne devienne un processus zombie incontrôlé.

Une fois tué, le fichier journal du Wrapper cessera simplement d'enregistrer à ce moment. Toute sortie de journal Java au-delà de ce point n'apparaîtra pas dans le fichier journal.

Compatibilité :	1.0.0
Éditions :
Plateformes :

Le processus Java peut être tué de force de la même manière que le processus Wrapper. Encore une fois, cela ne devrait normalement pas être fait, sauf dans le cadre de vos tests. Vous pouvez utiliser la propriété wrapper.java.pidfile pour demander au Wrapper d'écrire l'identifiant de processus du processus Java.

Par défaut, lorsque la JVM est tuée de cette manière, le Wrapper considérera qu'il s'agissait d'un plantage et redémarrera l'application dans une nouvelle JVM.

jvm 1    | ...
wrapper  | JVM exited unexpectedly.
wrapper  | Launching a JVM...
jvm 2    | WrapperManager: Initializing...
jvm 2    | ...

Si vous tuez le processus Java de cette façon, il n'aura pas la possibilité d'exécuter ses hooks d'arrêt, et ne sera donc pas arrêté proprement.

Compatibilité :	1.0.0
Éditions :
Plateformes :

Il existe également plusieurs façons d'arrêter la JVM depuis l'intérieur de la JVM. La méthode la plus courante, qui ne nécessite pas non plus de code spécifique au Wrapper, consiste simplement à appeler System.exit(0). Lorsque cela se produit, la JVM commencera son processus d'arrêt habituel, y compris l'exécution de tous les hooks d'arrêt enregistrés.

jvm 1    | ...
jvm 1    | Stopping...
wrapper  | <-- Wrapper Stopped

L'argument de la méthode exit est utilisé pour spécifier un code de sortie pour la JVM. Les codes de sortie peuvent être très utiles pour aider l'application qui a démarré la JVM à comprendre ce qui s'est passé. Le Wrapper est capable de reconnaître différents codes de sortie, puis d'effectuer diverses actions selon ce que vous souhaitez faire. Veuillez consulter la page de la propriété wrapper.on_exit.<n> pour plus d'informations.

Java vous fournit également Runtime.getRuntime().halt(0), qui permet d'arrêter la JVM sans exécuter aucun des hooks d'arrêt enregistrés. Bien que cela puisse être utile dans certains cas, nous ne recommandons pas son utilisation avec le Wrapper, car le Wrapper n'aura aucun moyen de savoir que la JVM a été arrêtée intentionnellement. Lorsque la JVM se termine de cette façon, le Wrapper l'interprétera comme un plantage de la JVM ou une sortie inattendue, et redémarrera donc la JVM.

jvm 1    | ...
wrapper  | JVM exited unexpectedly.
wrapper  | Launching a JVM...
jvm 2    | WrapperManager: Initializing...

Si vous avez vraiment besoin de vous arrêter sans exécuter les hooks d'arrêt, veuillez essayer la méthode WrapperManager.stopimmediate(0) ci-dessous.

Compatibilité :	1.0.0
Éditions :
Plateformes :

Une autre méthode consiste à utiliser l'API du Wrapper en appelant WrapperManager.stop(0). Lorsque cela se produit, la JVM commencera son processus d'arrêt habituel, y compris l'exécution de tous les hooks d'arrêt enregistrés.

jvm 1    | ...
jvm 1    | Stopping...
wrapper  | <-- Wrapper Stopped

Compatibilité :	3.0.4
Éditions :
Plateformes :

Si vous souhaitez arrêter la JVM sans exécuter aucun des hooks d'arrêt enregistrés, vous pouvez le faire en appelant la méthode WrapperManager.stopImmediate(0). Cela notifiera le Wrapper que la JVM prévoit de s'arrêter, mais le fera ensuite sans exécuter les hooks d'arrêt.

jvm 1    | ...
wrapper  | <-- Wrapper Stopped

Compatibilité :	3.0.0
Éditions :
Plateformes :

Le Wrapper dispose d'une fonctionnalité qui vous permet d'enregistrer des filtres sur la sortie du journal de la console JVM et d'effectuer ensuite l'une des nombreuses actions lorsqu'il y a une correspondance. Une de ces actions est l'action SHUTDOWN. Veuillez consulter les propriétés wrapper.filter.action.<n> et wrapper.filter.trigger.<n> pour une liste complète des actions disponibles.

Les filtres peuvent être très puissants car ils permettent d'ajouter des fonctionnalités à une application sans nécessiter de code Java. Un filtre peut être entièrement configuré dans le fichier de configuration du Wrapper.

Pour arrêter la JVM chaque fois que l'application a journalisé le texte Oops, vous spécifieriez un ensemble de propriétés comme suit.

wrapper.filter.trigger.1=Oops
wrapper.filter.action.1=SHUTDOWN

jvm 1    | Hey I heard someone say Oops...
wrapper  | Filter trigger matched.  Shutting down.
jvm 1    | Stopping...
wrapper  | <-- Wrapper Stopped

Il existe également un certain nombre d'autres fonctionnalités en plus des filtres qui vous permettent de spécifier qu'une certaine action a lieu. Celles-ci peuvent toutes spécifier une action SHUTDOWN. Voici des exemples des propriétés suivantes :

• wrapper.on_exit.<n>
• wrapper.timer.<n>.action
• wrapper.check.deadlock.action
• wrapper.event.<event_name>.command.block.action