Starten und Steuern Ihrer Anwendung (Windows)

Unter Windows ist es möglich, eine Java-Anwendung entweder als eine Desktop-Anwendung oder als einen Windows-Dienst im Hintergrund laufen zu lassen. Im Falle eines Dienstes muß der Wrapper imstande sein, installiert, entfernt, gestartet, angehalten oder seinen Status abgefragt bekommen zu werden. Abhängig davon, ob die Anwendung eine GUI besitzt oder beabsichtigt wird, diese in einem Befehlszeilenfenster auszuführen, entscheidet auch darüber, wie sie ausgeführt wird.

Festzugeordnete Batch-Dateien

Auf Windows-Systemen ist der übliche Weg, den Wrapper zu starten, von festzugeordneten Batch-Dateien Gebrauch zu machen, die jede Aktion ausführen, um den Wrapper zu steuern. Dies ermöglicht es für den Enduser auf die Batch-Datei-Icons doppelzuklicken oder Links in den Menüs einzurichten.

Konfiguration der Batch-Dateien

Wenn Sie in das Verzeichnis %WRAPPER_HOME%\src\bin der Wrapper-Distribution sehen, werden Sie eine Anzahl von Batch-Vorlagendateien sehen, die jede für sich für einen spezifischen Task genutzt werden. (Es gibt andere Dateien in dem Verzeichnis, die an anderer Stelle auf dieser Seite beschrieben werden.)

Beim Einrichten des Wrappers mit einer spezifischen Anwendung können Sie wählen, welcher der oben genannten Batch-Dateien für die Anwendung am sinnvollsten ist. Z.B., wenn eine Anwendung die Funktion, angehalten zu werden, nicht unterstützt, werden die Dateien PauseApp-NT.bat.in und ResumeApp-NT.bat.in nicht benötigt.

Batch-Dateien anpassen

NOTE

(Abhängig davon, wie Ihr Datei-Explorer auf Ihrem System konfiguriert ist, kann es sein, dass Sie Dateiendungen nicht sehen.)

Für jede benötigte Datei kopieren Sie diese bitte einfach in den bin-Ordner Ihrer Anwendung. Indem Sie dies tun, benennen Sie den Dateinamen um, indem Sie die Umbenennug der App mit dem Namen der Anwendung durchführen und am Ende .in entfernen.

Beispiel für den Ersatz von Dateinamen:
App.bat.in             -> MyApp.bat
InstallApp-NT.bat.in   -> InstallMyApp-NT.bat
StartApp-NT.bat.in     -> StartMyApp-NT.bat
StopApp-NT.bat.in      -> StopMyApp-NT.bat
UninstallApp-NT.bat.in -> UninstallMyApp-NT.bat

Der Beginn aller Dateinamen enthält einen Abschnitt, der individuell an die Dateinamenbenennung und die Verzeichnisstruktur Ihrer Anwendung angepasst werden kann.

HelloWorldServer.java (Change)
rem -----------------------------------------------------------------------------
rem These settings can be modified to fit the needs of your application
rem Optimized for use with version @wrapper.version@ of the Wrapper.

rem The base name for the Wrapper binary.
set _WRAPPER_BASE=wrapper

rem The name and location of the Wrapper configuration file.   This will be used
rem  if the user does not specify a configuration file as the first parameter to
rem  this script.  It will not be possible to specify a configuration file on the
rem  command line if _PASS_THROUGH is set.
set _WRAPPER_CONF_DEFAULT=../conf/wrapper.conf

rem _PASS_THROUGH tells the script to pass all parameters through to the JVM as
rem  is.
rem set _PASS_THROUGH=true

rem Do not modify anything beyond this point
rem -----------------------------------------------------------------------------

In einer Konsole ausführen

Starten der Anwendung

Das Ausführen der Anwendung in einer Konsole (Befehlszeilenfenster) kann getan werden, indem man innerhalb des Dateiexplorers auf die MyApp.bat-Batch-Datei klickt. Sie können es auch tun, indem Sie ein Befehlszeilenfenster öffnen und dann die Batch-Datei von der Befehlszeile aus ausführen. Aufgrund der Art, wie das Wrapper-Skript sein aktuelles Verzeichnis festlegt, ist es nicht notwendig, diese Batch-Datei von innerhalb des bin-Verzeichnisses auszuführen.

Ausgabebeispiel:
MyApp.bat
wrapper  | --> Wrapper Started as Console
wrapper  | Java Service Wrapper Professional Edition 64-bit {version}
wrapper  |   Copyright (C) 1999-{year} Tanuki Software, Ltd. All Rights Reserved.
wrapper  |     https://wrapper.tanukisoftware.com
wrapper  |   Licensed to {licensee}
wrapper  |
wrapper  | Launching a JVM...
jvm 1    | WrapperManager: Initializing...

Beenden der Anwendung

Die Anwendung kann durch Drücken von STRG-C in der Konsole (Befehlsfenster) beendet werden. Dies sorgt dafür, dass der Wrapper die Anwendung korrekt beendet. Für weitere Optionen besuchen Sie bitte die Seite how to stop a console application.

Ausführen als ein Windows Dienst

NOTE

Bevor Sie fortfahren, stellen Sie bitte sicher, dass Sie alle Windows Dienst bezogenen Eigenschaften in der wrapper.conf-Datei konfiguriert haben. Sie sollten auch sicherstellen, dass die Anwendung korrekt im Konsolen-Modusausgeführt wird.

Installation als ein Windows Dienst

Die Anwendung kann durch Doppelklick auf die InstallMyApp-NT.bat-Batchdatei von innerhalb des Dateiexplorers als ein Dienst installiert werden. Dies kann auch durch Öffnen eines Befehlsfensters und anschliessendes Ausführen des installierten Skripts von der Befehlszeile aus getan werden. Wenn der Dienst erfolgreich installiert wurde, wird sich das Skript sofort beenden.

Wenn irgendwelche Probleme auftreten würden, dann gäbe es eine Fehlermeldung, die das angezeigte Problem beschreibt. Das Skript wartet dann bis der User eine Taste drückt, bevor es sich beendet.

Befehls- und Ausgabebeispiel:
InstallMyApp-NT.bat
wrapper  | My Application service installed.

Starten und Beenden des Windows Dienstes

Der Dienst kann nun durch Nutzung der jeweiligen Batch-Dateien gestartet und angehalten werden.

Befehls- und Ausgabebeispiel:
StartMyApp-NT.bat
wrapper  | Starting the My Application service...
wrapper  | My Application started.
StopMyApp-NT.bat
wrapper  | Stopping the My Application service...
wrapper  | My Application stopped.

Da der Dienst ein normaler Windows Dienst ist, können Sie ihn auch via Systemsteuerung-Dienste ([Systemsteuerung] - [System and Sicherheit] - [Administrative Tools] - [Dienste]) unter Windows als Dienst auswählen und dann auf die "Dienst starten"-Schaltfläche klicken.

Zusätzlich kann der Dienst durch Nutzung der net start MyApp und net stop MyApp-Befehle gesteuert werden.

Befehls- und Ausgabebeispiel:
net start MyApp
The My Application service is starting....
The My Application service was started successfully.
net stop MyApp
The My Application service is stopping..
The My Application service was stopped successfully.

NOTE

Die net start x- und net stop x-Befehle haben Probleme mit Diensten, die eine etwas längere Zeit zum Starten oder Beenden brauchen. In den meisten Fällen funktionieren sie, aber wenn ein Dienst mehr als ein paar Sekunden braucht, um sich zu beenden, wird der net stop x-Befehl zurückmelden, dass der Dienst beendet wurde, auch wenn er sich noch im Beenden-Prozess befindet. Dies kann zu Problemen führen, wenn ein Skript warten muß bis ein Dienst tatsächlich beendet wurde, bevor es fortfährt. Durch Nutzung des Wrappers können Sie solche Probleme beim Starten, Beenden des Dienstes vermeiden.

Die Wrapper-Methode des Startens und Beendens des Dienstes ist auch in Skripts nützlich, da es nicht die Eingabe des tatsächlichen Namens, unter dem der Dienst installiert ist, benötigt und dieser überall, außer in der wrapper.conf-Datei, vorhanden ist. Dies erübrigt das manuelle Ändern von mehreren Dateien, wenn der Dienstname geändert wird.

Wenn die wrapper.ntservice.starttype-Eigenschaft auf AUTO_START festgelegt ist, dann wird der Dienst gestartet werden, wann immer die Maschine neu gestartet wird.

Deinstallation (Entfernen) als Windows Dienst

Der Dienst kann deinstalliert werden, indem die UninstallMyApp-NT.bat Batch-Datei ausgeführt wird. Wenn er aktuell läuft, wird er zuerst beendet werden.

Befehls- und Ausgabebeispiel:
UninstallMyApp-NT.bat
wrapper  | Service is running.  Stopping it...
wrapper  | Waiting to stop...
wrapper  | My Application stopped.
wrapper  | My Application service removed.

Befehlsbasierte Batch-Datei

Einige Anwendungen, die von UNIX-basierten Betriebssystemen portiert wurden, mögen mit einem UNIX-Stil-Befehlsskript besser laufen, um den Dienst zu kontrollieren. Die befehlsbasierte Batch-Datei kombiniert die gesamte Funktionalität aller individuellen dedizierten Batch-Dateien zusammen in eine einzelne Datei, die einen Befehl als einen Parameter nimmt.

Einrichten von Batch-Dateien

Wenn Sie in den Ordner der Wrapper-Distribution %WRAPPER_HOME%\src\bin sehen, sehen Sie eine Vorlagen-Befehlsbatchdatei, AppCommand.bat.in.

Kopieren Sie einfach diese Datei in den bin-Ordner Ihrer Anwendung. Wenn Sie dies so tun, nennen Sie bitte die Datei um, ersetzen SieApp mit dem Namen Ihrer Anwendung und entfernen Sie das .in am Ende.

Beispiel für das Ersetzen von Dateinamen:
MyServerCommand.bat.in             -> MyServerCommand.bat
MyServer.bat.in   -> MyServer.bat

Der Start aller Dateien enthält einen Abschnitt, welcher angepasst werden kann, um den Dateibenennungs- und Verzeichnisstrukturen Ihrer Anwendung zu entsprechen.

Skriptkonfigurationsbereich:
rem -----------------------------------------------------------------------------
rem These settings can be modified to fit the needs of your application
rem Optimized for use with version @wrapper.version@ of the Wrapper.

rem The base name for the Wrapper binary.
set _WRAPPER_BASE=wrapper

rem The name and location of the Wrapper configuration file.
rem  (Do not remove quotes.)
set _WRAPPER_CONF="../conf/wrapper.conf"

rem _FIXED_COMMAND tells the script to use a hard coded command rather than
rem  expecting the first parameter of the command line to be the command.
rem  By default the command will will be expected to be the first parameter.
rem set _FIXED_COMMAND=console

rem _PASS_THROUGH tells the script to pass all parameters through to the JVM
rem  as is.  If _FIXED_COMMAND is specified then all parameters will be passed.
rem  If not set then all parameters starting with the second will be passed.
set _PASS_THROUGH=true

rem Do not modify anything beyond this point
rem -----------------------------------------------------------------------------

Ausführen des Skripts

Die befehlsbasierte Batch-Datei ist selbstdokumentierend, wenn der User versucht, diese ohne Parameter auszuführen und das Skript zeigt die Nutzung an.

Nutzung mit aktiviertem _PASS_THROUGH :
Usage: TestWrapperCommand [ console {JavaAppArgs} : start : stop : restart : pause : resume : status : permissions : privileges : install {JavaAppArgs} : installstart {JavaAppArgs} : update {JavaAppArgs} : remove : setup : teardown ]

Commands:
  console      Launch in the current console.
  start        Start the Service.
  stop         Stop the Service.
  restart      Stop the Service if running and then start.
  pause        Pause the Service if running.
  resume       Resume the Service if paused.
  status       Query the current status of the Service.
  permissions  Query the current permissions of the Service.
  privileges   Query the current privileges of the Service.
  install      Install the Service.
  installstart Install the Service and then start running it.
  update       Update an installed Service.
  remove       Uninstall the Service.
  setup        Setup the Wrapper (for registration to the Windows Event Log).
  teardown     Teardown the Wrapper (unregister from the Windows Event Log).

JavaAppArgs:
  Optional arguments which will be passed to the Java application.
Nutzung mit deaktiviertem _PASS_THROUGH :
Usage: TestWrapperCommand [ console : start : stop : restart : pause : resume : status : permissions : privileges : install : installstart : update : remove : setup : teardown ]

...

Es gibt ein paar Unterschiede zwischen dieser Batch-Datei für Windows und dem UNIX-Skript. Das UNIX-Skript kann genutzt werden, um den in einer Konsole ausgeführten Wrapper zu beenden; jedoch ist es nicht möglich, dies mit der Batch-Datei für Windows zu tun. Zusätzlich fehlt der dump-Befehl in der Batch-Datei unter Windows.

Wie Sie sehen können, bietet die befehlsbasierte Batch-Datei eine breite Reihe von Fähigkeiten an:

Als ein Beispiel kann der Wrapper in einer Konsole durch Nutzung des folgenden Befehls gestartet werden:

MyApp.bat console
wrapper  | --> Wrapper Started as Console
wrapper  | Java Service Wrapper Professional Edition 64-bit {version}
wrapper  |   Copyright (C) 1999-{year} Tanuki Software, Ltd. All Rights Reserved.
wrapper  |     https://wrapper.tanukisoftware.com
wrapper  |   Licensed to {licensee}
wrapper  |
wrapper  | Launching a JVM...
jvm 1    | WrapperManager: Initializing...

Um andere Befehle auszuführen, ersetzen Sie bitte einfach den "console"- Befehl mit dem Befehl, welchen Sie auszuführen wünschen.

Standalone-Programmdatei

Der Java Service Wrapper kann auch direkt, ohne Nutzung einer Batch-Datei, ausgeführt werden.

Wrapper-Nutzung

Wenn die wrapper-Programmdatei ohne irgendwelche Parameter oder mit einem "-?" gestartet wird, wird die folgende Nutzungsausgabe angezeigt werden.

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

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

where <command> can be one of:
  -c  --console run as a Console application
  -su --setup   SetUp the wrapper
  -td --teardown TearDown the wrapper
  -t  --start   starT an NT service
  -a  --pause   pAuse a started NT service
  -e  --resume  rEsume a paused NT service
  -p  --stop    stoP a running NT service
  -i  --install Install as an NT service
  -it --installstart Install and sTart as an NT service
  -u  --update Update an installed NT service
  -r  --remove  Uninstall/Remove as an NT service
  -l=<code> --controlcode=<code> send a user controL Code to a running NT service
  -d  --dump    request a thread Dump
  -q  --query   Query the current status of the service
  -qs --querysilent Silently Query the current status of the service
  -h  --hostid  prints 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 wrapper.conf to use.  Name must be absolute or relative
  to the location of bin\wrapper

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

  --customize  This command will allow you to customize your Wrapper executable.
    The following [customize arguments] are available:
      --target <target file> Specifies the name and location of the customized
          Wrapper executable.  This property is mandatory as it is not possible
          or safe to guess a default file name.
      --icon <icon file> Specifies the custom icon for your Wrapper executable.
      --passthrough If set, the new Wrapper executable will precede the
                    whole command line to the wrapped application.
      --conf <conf file> Specifies the default location of the conf file
      --manufacturer <Manufacturer> Sets the Manufacturer for the binary

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

Starten der Anwendung

Um den Wrapper als eine Konsolenanwendung auszuführen, würden Sie den -c-Befehl spezifizieren, gefolgt von der wrapper.conf-Datei. Der Speicherort der wrapper.conf-Datei kann ein absoluter oder relativer Speicherpfad sein. Wenn ein relativer Pfad genutzt wird, ist der Pfad stets relativ zum Speicherort der wrapper.exe-Datei, nicht zum aktuellen Verzeichnis.

Befehlsbeispiel:
wrapper.exe -c ..\conf\wrapper.conf

Installation der Anwendung als einen Dienst

Um die Anwendung als einen Windows Dienst zu installieren, führen Sie Folgendes aus:

Befehlsbeispiel:
wrapper.exe -i ..\conf\wrapper.conf

Starten der Anwendung als ein Dienst

Sobald installiert, kann der Dienst wie jeder anderen Windows Dienst gestartet werden. Wenn wrapper.ntservice.starttype auf AUTO_START eingestellt wurde, sobald installiert, wird dann der Dienst das nächste Mal, wenn die Maschine neu gestartet wird, gestartet werden. Es ist auch möglich, den Dienst von Systemsteuerung aus zu starten ([Systemsteuerung] - [System und Sicherheit] - [Administrative Tools] - [Dienste]) unter Windows durch Auswahl des Dienstes und dann Auswählen des Dienstes und dann Klicken der "Dienst starten "-Schaltfläche oder via einer der folgenden Befehle:

Befehlsbeispiel:
wrapper.exe -t ..\conf\wrapper.conf
net start MyApp

NOTE

Die net start x- und net stop x- Befehle haben Probleme mit Diensten, die beim Starten oder Beenden viel Zeit beanspruchen. In den meisten Fällen funktionieren sie, aber wenn ein Dienst mehr als ein paar Sekunden beansprucht, um sich zu beenden, wird der net stop x Befehl zurückgeben, dass der Dienst beendet wurde, auch dann, wenn dieser sich noch im Beenden-Prozess befindet. Dies kann zu Problemen führen, wenn ein Skript warten muß bis ein Dienst tatsächlich beendet wurde. Durch Einsatz des Wrappers, um den Dienst zu starten oder zu beenden, haben Sie die Sicherheit, dass solche Probleme nicht auftreten.

Die Wrapper-Methode des Startens und Beendens des Dienstes ist auch in Skripts nützlich, da es nicht die Eingabe des tatsächlichen Namens, unter dem der Dienst installiert ist, erfordert und dieser überall, außer in der wrapper.conf-Datei, vorhanden ist. Dies erübrigt das manuelle Ändern von mehreren Dateien, wenn der Dienstname geändert wird.

Beenden der Anwendung als ein Dienst

Der Dienst kann durch Nutzung des Dienste-Tools von der Systemsteuerung ([Systemsteuerung] - [System und Sicherheit] - [Administrative Tools] - [Dienste]) und gefolgt vom Klicken auf die "Dienst starten"-Schaltfläche oder durch einer der folgenden Befehle beendet werden.

Befehlsbeispiel:
wrapper.exe -p ..\conf\wrapper.conf
net stop MyApp

Deinstallation der Anwendung als ein Dienst

Wenn Sie die Anwendung als ein Windows Dienst installieren möchten, führen Sie bitte den folgenden Befehl aus:

Befehlsbeispiel:
wrapper.exe -r ..\conf\wrapper.conf

Wenn der Dienst zu dem Zeitpunkt, wenn er deinstalliert wird, läuft, wird der Dienst korrekt beendet und dann entfernt.

Abfragen des Status der Anwendung

Der Wrapper kann genutzt werden, um den Dienststatus manuell oder von innerhalb einer Batch-Datei abzufragen. Die kann nützlich für die Installation von Skripts sein, welche den aktuellen Status der Dienstkonfiguration kennen müssen.

Befehl-und Ausgabebeispiel:
wrapper.exe -q ..\conf\wrapper.conf
wrapper  | The My Application Service is installed.
wrapper  |   Start Type: Automatic
wrapper  |   Interactive: Yes
wrapper  |   Running: No

Wenn mit dem "-q"-Befehl ausgeführt, wird der Wrapper den aktuellen Status auf der Konsole anzeigen, "-qs" Befehl läuft im Hintergrund ab. Der Wrapper wird dann einen Exit-Code ausgeben, welcher eine Kombination von den folgenden Bits ist:

Ein Exit-Code von "15" (=1+2+4+8) z.B. zeigt an, dass der Dienst installiert ist, läuft, interaktiv und konfiguriert ist, automatisch zu starten, wenn das System gestartet wird. Ein Exit-Code von "0" (Null) bedeutet, dass der Dienst aktuell nicht installiert ist.

Verweis: Starten Ihrer Anwendung mit dem Wrapper