Mit Beginn der Java 1.3 Version beinhaltete Java die Fähigkeit einen besonderen Thread zu registrieren, als ein Shutdown-Hook bezeichnet, welcher durch die JVM ausgeführt wird, sobald diese bereit ist, heruntergefahren zu werden. Ohne einen Shutdown-Hook, könnte eine Anwendung nicht wissen, wie diese heruntergefahren werden kann. Auf diese Weise gäbe es keine Möglichkeit, zu wissen, dass es jede in Bearbeitung befindliche Information vervollständigen und alle weiteren Daten erhalten müßte.

Wir gehen hier auf Shutdown-Hooks nicht im Detail ein, sondern geben hier ein Beispiel, wie solch einer aussehen und mit der JVM registriert werden müsste.

Registrierung eines Shutdown-Hooks:

Thread shutdownHook = new Thread( "myapp-shutdown-hook" )
    {
        public void run()
        {
            System.out.println( "Starten des Herunterfahrens der MyApp..." );
            // Aufräumarbeiten.
            System.out.println( "MyApp-Herunterfahren beendet." );
        }
    };
Runtime.getRuntime().addShutdownHook( shutdownHook );

Es ist gewöhnlich und üblich, mehrfache Shutdown-Hooks registrieren zu lassen. Gewöhnlich wird jede Anwendung seinen eigenen Shutdown-Hook registrieren, sofern es notwendig ist. Registrierung von Shutdown-Hooks sollte als Teil eines Initializierungsprozesses getan werden, damit mit Shutdowns - unabhängig des Timings - richtig umgegangen wird. In den meisten Fällen reicht dafür, einen Shutdown-Hook zu registrieren.

Einen Shutdown-Hook entfernen:

Es ist gewöhnlich möglich, den Shutdown-Hook so zu codieren, ohne dass dies notwendig ist. Aber wenn Sie meinen, einen Shutdown-Hook entfernen zu müssen, kann es wie folgt getan werden:

Runtime.getRuntime().removeShutdownHook( shutdownHook );

JVM-Shutdown:

Wenn die JVM das Herunterfahren beginnt, wird es alle registrierten Shutdown-Hooks durchlaufen und jeden als einen neuen Thread starten. Diese Shutdown-Hook-Threads laufen dann parallel ab, bis diese alle abgearbeitet sind. Wenn der letzte Shutdown-Hook abgeschlossen ist, wird die JVM sofort beendet,und alle anderen Threads, die immer noch laufen, werden zwangsweise geschlossen.

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

Ein Problem mit Shutdown-Hooks ist, dass sie möglicherweise Stunden dauern können bis sie beendet sind. Während dieser Zeit gibt es normalerweise keine andere Möglichkeit, Java darüber zu informieren, früher herunterzufahren. Der Wrapper hat für dieses Problem einen Workaround, indem er das konfigurierbare JVM Exit Timeout, wie unten beschrieben, benutzt.

Wenn Sie beginnen, die JVM, die mit dem Java Service Wrapper integriert war, herunterzufahren, wird die JVM den internen Shutdown-Hook des Wrappers ausführen. Der Wrapper benutzt seinen eigenen Shutdown-Hook, um ein sauberes Herunterfahren der Anwendung, die durch den Wrapper eingehüllt ist und danach auch das Löschen/Aufräumen des Wrappers selbst, zu beginnen.

Wenn Sie wie die meisten Nutzer die Integrationsmethode #1 (WrapperSimpleApp) oder Methode #4 (WrapperJarApp) für Ihre Anwendung benutzen, dann wird der Shutdown-Hook des Wrappers weitgehend sofort abgearbeitet werden.

Wenn Sie jedoch von folgender Integrationsmethode #2 Gebrauch machen oder Methode #3 benutzen, dann wird der Shutdown-Hook des Wrappers ausgeführt werden bis die Anwendung beendet wurde. Für Methode #2 WrapperStartStopApp, ist dies dann, bis die Hauptmethode der registrierten shutdown Klasse sich beendet. Für die Methode #3 WrapperListener Implementierung, dies ist dann, wenn die WrapperListener.stop() Methode sich beendet.

Der Wrapper definiert einen Shutdown-Timeout, welcher die maximale Zeitspanne ist, die dem Shutdown-Hook des Wrappers zugestanden wird, um sich selbst zu beenden. Wenn es dem Wrapper Shutdown nicht gelingt, darüber mitzuteilen, dass es innerhalb der Timeout-Zeitspanne sich beendet hat, dann wird der Wrapper annehmen, dass der Shutdown-Prozess abgestürzt ist und die JVM zwangsweise beenden. Dies wird getan, um Shutdown-Probleme zu vermeiden, die andererseits die Anwendung in einem nicht brauchbaren Zustand zurücklassen würden. Der Shutdown-Timeout ist standardmäßig auf 30 Sekunden eingestellt, und kann über die Eigenschaft wrapper.shutdown.timeout konfiguriert werden.

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

Nachdem der Shutdown-Hook des Wrappers sich beendet hat und der Wrapper darüber informiert wurde, dass die JVM zum Shutdown bereit ist, geht der Wrapper in einen Modus über, in dem er einfach darauf wartet, dass sich die JVM selbst beendet. Erinnern Sie sich daran, dass die JVM alle registrierten Shutdown-Hooks parallel startet. Sie wird warten, bis die letzte beendet wurde und dann sich selbst schließen. Wenn irgendeine der anderen Shutdown-Hooks eine lange Zeit beanspruchen, um sich zu beenden, dann könnte dies eine Weile dauern. Gleich wie der obengenannte Shutdown Timeout ist der Wrapper ausgelegt nach einer Weile in einen Timeout-Zustand zu gehen,um zu vermeiden, dass die Anwendung in einen nicht erreichbaren Zustand übergleitet. Das Timeout beläuft sich standardmäßig auf 15 Sekunden, und kann unter Benutzung der Eigenschaft wrapper.jvm_exit.timeout konfiguriert werden.

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

Sobald der letzte der Shutdown-Hooks beendet wurde, sollte sich der JVM-Prozess fast unmittelbar beenden. Ein bekannter Grund, warum ein Beenden längere Zeit dauern kann ist der, dass wenn eine Speicherabbild-Datei gespeichert wurde, während das Heap-Profiling der JVM aktiv war.

Kompatibel :	1.0.0
Editionen :
Betriebssysteme :

Die erste Methode, die Sie antreffen werden, ist sehr wahrscheinlich, einfach die Tastenkombination CTRL-C während der Wrapper innerhalb einer Konsole oder eines Terminals abläuft. Diese Methode erfordert keine speziellen Programmierkenntnisse und kann fast mit jeder Anwendung benutzt werden.

Windows:

Wenn der Benutzer in Windows CTRL-C drückt, leitet der Wrapper die Anforderung an den Java-Prozess weiter. Java erledigt die Anforderung dann einfach, indem es alle Shutdown-Hooks die mit der Anwendung registriert wurden, startet.

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

UNIX:

Auf UNIX-Plattformen, ein CTRL-C veranlasst ein INT-Signal an den Wrapper verschickt zu werden. Dadurch erscheint die Ausgabe etwas unterschiedlich.

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

CTRL-C:

Manchmal, wenn Sie eine Anwendung entwickeln, kann es ermüdend sein, ständig auf die Anwendung zu warten, um sich korrekt zu beenden. Wenn Sie sie wirklich sofort beenden möchten, erlaubt der Wrapper Ihnen via CTRL-C ein zweites Mal, die JVM zu beenden. Während es sehr nützlich sein kann, hat dies den Nachteil, dass die Daten möglicherweise nicht korrekt gespeichert werden, weil die Shutdown-Hooks nicht komplett bis zum Ende ausgeführt wurden.

...
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

Deaktivieren Sie CTRL-C:

Den meisten Usern gefällt dieses Feature, aber im Falle, wenn Sie der JVM permanent die Möglichkeit geben wollen, sauber herunterzufahren, können Sie das Feature des sofortigen Shutdown über den folgenden Link wrapper.disable_forced_shutdown -Eigenschaft, beginnend mit der Wrapper Version 3.5.15 ausschalten.

Es wird Fälle geben, in denen Sie es gezielt vermeiden möchten, dass Benutzer die Anwendung mit CTRL-C beenden können. Dies kann einfach unter Nutzung des folgenden Links wrapper.ignore_signals-Eigenschaft erreicht werden. Bitte beachten Sie, dass wenn Sie es so tun, werden Sie natürlich einer der anderen 2 Methoden nutzen müssen, um die Anwendung herunterzufahren.

wrapper  | CTRL-C trapped, but ignored.

Kompatibel :	1.0.0
Editionen :
Betriebssysteme :

Auf UNIX-Plattformen ist es auch möglich ein TERM-Signal an den Wrapper-Prozess abzusenden. Dies ist tatsächlich der gewöhnliche Weg, mit dem die Shell-Skripte die mit dem Wrapper geliefert wurde, heruntergefahren werden.

Das TERM-Signal funktioniertfast genauso wie die CTRL-C-Methode von weiter oben.

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

Sie können dieses Signal von der Befehlszeile aus absenden, indem Sie das folgende Kommando benutzen.

kill {pid}

Die {pid} sollte mit der Prozess-ID des Wrappers ersetzt werden. Wenn Sie wünschen, dies progammiertechnisch zu tun, können Sie dem Wrapper seine gegenwärtige Prozess-Id in eine Pid-Datei unter Benutzung der wrapper.pidfile Eigenschaft speichern lassen. Wenn Sie das Shell-Skript des Wrappers benutzen, dann sollte sich diese Datei standardmäßig im gleichen Verzeichnis wie die Wrapper-Programmdatei befinden.

Die wrapper.ignore_signals Eigenschaft kann auch benutzt werden, um diese Art des Shutdowns auszuschalten.

wrapper  | TERM trapped, but ignored.

Kompatibel :	1.0.0
Editionen :
Betriebssysteme :

Wenn es als Windows Dienst ausgeführt wird, ist es möglich, diesen Dienst zu beenden, indem Sie einen von zahlreichen Befehlen benutzen:

• Zuerst beenden Sie den Dienst über das Systemsteuerungselement Dienste ([Systemsteuerung] - [Administrator Tool] - [Dienste]).
• Zweitens benutzen Sie den net Befehl von der Befehlszeile:

net stop myapp

• Und drittens benutzen Sie den sc Befehl, auch von der Befehlszeile:

sc stop myapp

In jedem Fall, wenn ein Befehl ausgegeben wurde, einen Dienst zu beenden, wird der Windows Dienst Kontrol-Manager den Dienst-Shutdown-Prozess steuern und melden, wenn dieser beendet wurde. Der Wrapper antwortet immer darauf, indem er versucht die JVM sauber herunterzufahren.

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

Wenn das komplette System heruntergefahren wird, wird der Wrapper vor dem Shutdown vom Betriebssystem beendet. Einige Windows-Versionen ignorieren Rückmeldungen, dass der Dienst heruntergefahren wird und beenden einfach den Dienst, wenn es zu lange dauert. Wenn dies passiert, kann es sein, dass Sie eine abgeschnittene Logdatei sehen, da der Wrapper und seine JVM zwangsweise durch das Betriebssystem beendet werden.

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

Kompatibel :	3.1.1
Editionen :
Betriebssysteme :

Der Wrapper kann so konfiguriert werden, dass er eine Anchor-Datei ausgibt unter Nutzung der wrapper.anchorfile Eigenschaft. Ein Anker wird von Schiffen genutzt, um das Schiff daran zu hindern, wegzutreiben. Der Wrapper nutzt diese Datei in vielerlei Hinsicht auf die gleiche Art. Es wird die Ankerdatei beim Hochstarten erstellen und dann regelmäßig prüfen, ob diese immer noch existiert. Wann und wenn immer die Datei gelöscht wird, wird der Wrapper mit dem Prozess des Herunterfahrens beginnen.

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

Auf UNIX, wenn Sie das Shell-Script verändern konnten, um Systemsignale zu ignorieren, wird es diese Methode benutzen, um zu steuern, wann der Wrapper heruntergefahren werden sollte.

Kompatibel :	3.2.0
Editionen :
Betriebssysteme :

Der Wrapper kann konfiguriert werden, um nach einer Befehlsdatei zu schauen, die zahlreiche Befehle enthalten kann, die der Wrapper interpretieren wird. Der Ort dieser Datei kann unter Nutzung der wrapper.commandfile Eigenschaft bestimmt werden. Standardmäßig ist diese Option deaktiviert.

Befehle werden durch einfaches Erstellen einer Textdatei ausgeführt, die den Befehl enthält. Die Datei wird seitens des Wrappers gelöscht, sobald der Befehl ausgeführt würde.

STOP

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

Wenn diese Methode eingesetzt wird, es ist natürlich wichtig, das Verzeichnis, in dem sich die Befehlsdatei befindet, zu schützen, um sicherzustellen, dass nur Benutzer, die befehlsberechtigt sein sollen, Befehle auch ausführen können. Bitte sehen Sie in der Dokumentation der Eigenschaften der wrapper.commandfile Datei nach, um eine komplette Liste der verfügbaren Befehle zusammen mit ein paar Beispielen angezeigt zu bekommen.

Kompatibel :	3.0.4
Editionen :
Betriebssysteme :

Der Wrapper besitzt eine optionale Klasse, die es Ihnen ermöglicht, mit jedem Telnet-Client, den Wrapper von der Ferne aus zu steuern. Die Nutzung dieser Methode erfordert, dass Sie ein paar Zeilen Programmcode Ihrer Anwendung hinzufügen. Bitte sehen Sie in den javadocs WrapperActionServer nach, um eine umfassende Beschreibung der Klasse zu bekommen.

Um einen einfachen Server zu installieren, der dem Client nur das Herunterfahren des Wrappers erlaubt, versuchen Sie bitte, folgenden Programmcode hinzuzufügen:

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

Zusätzliche Aktionen können durch Aufruf der geeigneten Methoden, die in den javadocs gelistet sind, ausgeführt werden.

Sobald die Installation beendet wurde, können Sie sich nun mit dem Befehl telnet localhost 9999 verbinden. Nachdem Sie verbunden sind, drücken Sie einfach die S-Taste, und der Wrapper wird sauber heruntergefahren. Dies kann ein potentielles Sicherheitsrisiko beinhalten. Daher sollten Sie sicherstellen, diesen Port zu schützen, wenn er benutzt wird. Es ist auch möglich, das lauschende Socket mit dem localhost zu verbinden; auf diese Weise werden Remoteverbindungen unterbunden.

Kompatibel :	1.0.0
Editionen :
Betriebssysteme :

Als einen letzten Ausweg, oder als Bestandteil des Testens, kann es sein, dass Se den Wunsch haben, den Wrapper-Prozess zwangsweise zu beenden. Unter Windows können Sie dies durch Öffnen des Task Managers tun, um die wrapper.exe Datei unter der Registerkarte Prozesse zu markieren und dann Prozess beenden auszuwählen. Unter UNIX können Sie das Gleiche ausführen, indem Sie eine Variante des Befehls, den kill, kill -9 {pid} Befehl benutzen. In beiden Fällen müssen Sie sehr vorsichtig vorgehen, um zu vermeiden, dass Sie den falschen Prozess beenden.

Wenn Sie den Wrapper-Prozess auf diese Weile beenden, wird dieser sofort beendet und keine Möglichkeit haben, die JVM sauber herunterzufahren. Der Wrapper ist jedoch so konzipiert, das seine Java-Komponente den Java-Shutdown-Vorgang automatisch startet. Dies ist besonders wichtig, um zu vermeiden, dass die JVM in einen unkontrollierbaren Zombie-Prozess ausartet.

Sobald beendet, wird die Logdatei des Wrappers das Protokollieren in diesem Moment einfach beenden. Jede Java-Logausgabe nach diesem Zeitpunkt wird nicht im Dateilog verzeichnet.

Kompatibel :	1.0.0
Editionen :
Betriebssysteme :

Der Java-Prozess kann in vielerlei Hinsicht auf gleicher Weise wie der Wrapper-Prozess beendet werden. Zur Wiederholung: dies sollte normalerweise nicht getan werden; ausser als Bestandteil Ihres Testens. Sie können die wrapper.java.pidfile Eigenschaft benutzen, um dafür zu sorgen, dass der Wrapper die Java Prozess-Id ausgibt.

Standardmäßig, wenn die JVM auf diese Weise beendet wird, wird der Wrapper annehmen, dass es sich um einen Systemabsturz handelt und die Anwendung in einer neuen JVM starten.

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

Wenn Sie den Java-Prozess auf diese Weise beenden, wird es nicht die Möglichkeit haben, irgeneine seiner Shutdown-Hooksauszuführen, und wird so nicht sauber heruntergefahren werden.

Kompatibel :	1.0.0
Editionen :
Betriebssysteme :

Es gibt auch verschiedene Arten, wie man die JVM innerhalb der JVM beenden kann. Die am meisten eingesetzte Methode ist die, die auch nicht irgendeine Wrapper-spezifische Programmkodierung erfordert, sondern einfach durch den Aufruf von System.exit(0) erfolgt. Sobald dies erfolgt, wird die JVM ihren normalen Prozess des Herunterfahrens starten, der auch das Ausführen aller Shutdown-Hooks beinhaltet.

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

Das Argument der exit-Methode wird benutzt, um einen bestimmten Exit-Code für die JVM zu definieren. Exit-Codes können sehr nützlich sein, um der Anwendung, die die JVM startete, zu helfen, zu verstehen, ewas geschehen ist. Der Wrapper ist imstande, verschiedene Exit-Codes zu erkennen und danach verschiedene Aktionen auszuführen, je nachdem, was Sie beabsichtigen, zu tun. Bitte sehen Sie für detailliertere Information in den Eigenschaften von wrapper.on_exit.<n> nach.

Java stellt Ihnen auch eine Runtime.getRuntime().halt(0) Funktion bereit, die es ermöglicht, die JVM auch ohne das Starten von registrierten Shutdown-Hooks herunterzufahren. Während diese in bestimmten Fällen nützlich, sinnvoll sein kann, empfehlen wir diese nicht in Zusammenspiel mit dem Wrapper zu verwenden, da dieser nicht über irgendein Art von Wissen verfügt, dass die JVM auf beabsichtigte Weise heruntergefahren wurde. Wenn sich die JVM auf diese Weise beendet, wird der Wrapper dies als einen Absturz oder eines unerwarteten Beenden der JVM interpretieren und daher die JVM neu starten.

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

Wenn Sie wirklich herunterfahren müssen, ohne Shutdown-Hooks auszuführen, versuchen Sie bitte den folgenden Link, Methode: WrapperManager.stopimmediate(0) unten.

Kompatibel :	1.0.0
Editionen :
Betriebssysteme :

Eine andere Methode ist es, die Wrapper API durch Aufruf von WrapperManager.stop(0) zu nutzen. Wenn dies erfolgt, startet die JVM ihren normalen Shutdown-Prozess, inklusive dem Ausführen aller registrierten Shutdown-Hooks.

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

Kompatibel :	3.0.4
Editionen :
Betriebssysteme :

Wenn Sie die JVM beenden möchten, ohne die registrierten Shutdown-Hooks auszuführen, können Sie dies durch den Aufruf der WrapperManager.stopImmediate(0) -Methode tun. Diese informiert den Wrapper darüber, dass die JVM beabsichtigt, sich herunterzufahren;dies dann aber ohne Ausführen der Shutdown-Hooks erfolgt.

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

Kompatibel :	3.0.0
Editionen :
Betriebssysteme :

Der Wrapper besitzt ein Feature, welches Ihnen ermöglicht, Filter auf der Konsolen-Log-Ausgabe der JVM zu setzen und dann jedwede zahlreicher Aktionen auszuführen, sobald sich eine Übereinstimmung ergibt. Eine solche Aktion ist die SHUTDOWN -Aktion. Bitte sehen Sie in den Eigenschaften von wrapper.filter.action.<n> und wrapper.filter.trigger.<n> nach, um eine vollständige Liste der verfügbaren Aktionen zuerhalten.

Filter können sehr mächtig sein, weil sie es ermöglichen, einer Anwendung Funktionsvielfalt hinzufügen, ohne dass Java-Programmierkenntnisse erforderlich wären. Ein Filter kann vollständig innerhalb der Wrapper-Konfigurationsdatei eingestellt werden.

Um die JVM herunterzufahren, wann immer die Anwendung den Text Oops ins Log geschrieben hätte, müssten Sie eine Liste von Befehlen wie folgt definieren.

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

Es gibt zahlreiche andere Features neben den Filtern, die Ihnen erlauben, eine bestimmte Aktion festzulegen. Diese alle können eine SHUTDOWN-Aktion definieren. Beispiele sind die folgenden Eigenschaften:

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