アプリケーションを起動してコントロールする(Windows)

Windows 上で Java アプリケーションを、デスクトップアプリケーションとして、 あるいはバックグランドの Windows サービスとして、どちらの形式でも動かすことが可能です。 Windows サービスとして動かす場合、Wrapper のインストール、アンインストール、開始、停止、 ステータス(状況)のクエリー(問い合わせ)などが必要です。 アプリケーションが GUI 環境を持っているか、あるいはコンソール(コマンドウィンドウ)で動作させる仕様なのか、 それ次第でも、どのように動作させるべきか決まってきます。

下記に Wrapper を起動させる異なる方法を確認できます。

専用バッチファイル

Windows システム上で、Wrapper を起動する簡単な方法は、専用バッチファイルを利用することです。 Wrapper をコントロールする各アクションを操作することができます。 これでエンドユーザーが簡単にバッチファイルをダブルクリックやメニューのリンクを設定したりできます。

バッチファイルを設定する

Wrapper 配布物の「%WRAPPER_HOME%\src\bin」フォルダを覗くと、 それぞれ機能別のタスクに応じた、たくさんのバッチファイルテンプレートが見えます。 (このページで示す他のフォルダには、さらに他のファイルもあります。)

特定のアプリケーションが動作するように Wrapper を設定する際に、 アプリケーションの仕様に合わせて、上記のバッチファイルのどれかを選ぶことができます。 例えば、もしアプリケーションが「ポーズ(一時停止)」に対応していない場合には、 「PauseApp-NT.bat.in」や「ResumeApp-NT.bat.in」は必要ありません。

バッチファイルをカスタマイズする

注意

ご利用のコンピューターの設定状況によっては、拡張子が見えない場合がありますので、 拡張子が表示されるよう事前に設定を変更する必要があるかもしれません。

それぞれ必要なバッチファイルを利用するには、 アプリケーションのbin」フォルダにバッチファイルを単純にコピーしてご利用ください。 ファイル名のApp」部分をアプリケーション名に変更して、 ファイル名の拡張子.in」を削除してください。

ファイル名の変更例:
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

すべてのファイルの先頭に、カスタマイズできる変数のセクションが含まれています。

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 directory where the Wrapper binary (.exe) file is located. It can be
rem  either an absolute or a relative path. If the path contains any special
rem  characters, please make sure to quote the variable.
set _WRAPPER_DIR=

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.
rem If a relative path is specified, please note that the location is based on the
rem location of the Wrapper executable.
set _WRAPPER_CONF_DEFAULT="../conf/%_WRAPPER_BASE%.conf"

rem Makes it possible to override the Wrapper configuration file by specifying it
rem  as the first parameter.
rem set _WRAPPER_CONF_OVERRIDE=true

rem _PASS_THROUGH controls how the script arguments should be passed to the
rem  Wrapper. Possible values are:
rem  - commented or 'false': the arguments will be ignored (not passed).
rem  - 'app_args' or 'true': the arguments will be passed through the Wrapper as
rem                          arguments for the Java Application.
rem  - 'both': both Wrapper properties and Application arguments can be passed to
rem            the Wrapper. The Wrapper properties come in first position. The
rem            user can optionally add a '--' separator followed by application
rem            arguments.
rem NOTE - If _WRAPPER_CONF_OVERRIDE is set to true the above applies to arguments
rem        starting with the second, otherwise it applies to all arguments.
rem set _PASS_THROUGH=app_args

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

コンソールで動かす

アプリケーションを起動する

コンソール(コマンドウィンドウ)でアプリケーションを起動するには、ファイルエクスプローラーを開き、 MyApp.batバッチファイルをダブルクリックで実行します。 あるいは、コンソール(コマンドウィンドウ)を開いて、プロンプトから、そのバッチファイルを実行してください。 Wrapper がカレントディレクトリーを設定してくれるお陰で、 bin」ディレクトリー内部から、このバッチファイルを実行する必要はありません。

出力例:
MyApp.bat
wrapper  | --> Wrapperがコンソールとして開始しました
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  |   {licensee} へライセンスを割り当て
wrapper  |
wrapper  | JVM起動中...
jvm 1    | WrapperManager: 初期化中...

アプリケーションを終了する

アプリケーションを終了するには、 コンソール(コマンドウィンドウ)からCTRL]+[Cのキー操作で、アプリケーションを任意停止します。 これで、アプリケーションはキレイにシャットダウンされます。 さらに詳しくは「コンソールアプリケーションを停止するには?」ページをご覧ください。

アプリケーションを Windows サービスとして動かす

注意

作業に入る前に、 「wrapper.conf」ファイルのプロパティ設定で、 Windows サービス関連のプロパティが全て設定済みであることを確認してください。 また、コンソールモードで正しくアプリケーションが動作していることを検証してください。

Windows サービスとしてインストール

ファイルエクスプローラーから「InstallMyApp-NT.bat」バッチファイルをダブルクリックして実行する、 あるいは、コンソール(コマンドウィンドウ)を開いて、コマンドプロンプトから、 そのバッチファイルを実行することで、 アプリケーションを Windows サービスとしてインストールすることができます。 もし、正しくインストールできた場合、そのインストールバッチファイルは、ただちに終了します。

もし何か問題があった場合、「成功しなかった」というエラーメッセージが表示され、 ユーザーが何かキーを押すまで、応答待ちになります。

コマンドと出力例:
InstallMyApp-NT.bat
wrapper  | My Application service installed.

Windows サービスとして開始および停止する

各バッチファイルを利用して、サービスを開始したり停止したりすることができます。

コマンドと出力例:
StartMyApp-NT.bat
wrapper  | My Application サービスを開始中...
wrapper  | My Application started.
StopMyApp-NT.bat
wrapper  | My Application サービスを停止中...
wrapper  | My Applicationが停止しました.

動作しているサービスは普通の Windows サービスのため、サービスコントロールパネル ([コントロールパネル]→[システムとセキュリティ]→[管理ツール]→[サービス])を開き、 該当するサービスを選び、[サービスの開始]をクリックすることで、アプリケーションを開始することができます。

さらに、サービスの開始コマンド[net start MyApp]や サービスの停止コマンド[net stop MyApp]を使って、 サービスをコントロールすることができます。

コマンドと出力例:
net start MyApp
My Application サービスを開始中...
My Application サービスが正常に開始しました。
net stop MyApp
My Application サービスを停止中...
My Application サービスが正常に停止しました。

注意

net start x]や[net stop x]コマンドは、開始や停止に時間を要するサービスでは問題があります。 ほとんどのケースで動作はしますが、 もしサービスが停止するのに2、3秒かかる場合、まだ停止プロセスの途中であっても 「net stop x」コマンドは「サービスが停止されていた」と返してきます。 これは、処理前にサービスが本当に停止されるまでスクリプトが待機しなければならない状況で、問題になります。 そこで、サービスの開始や停止に Wrapper を利用すれば、そのような問題を確実に回避することができます。

wrapper.conf」ファイル以外、 他のどこかに存在するような、インストールされているサービスの実際の名前を要求しないため、 スクリプトを使ったサービス開始や停止をする Wrapper 手法は便利です。 そのため、もしサービス名が変更されても、複数のファイルを手作業で編集する必要がありません。

もし[wrapper.ntservice.starttype]プロパティが、 「AUTO_START」(自動スタート)に設定されている場合、 マシンが再起動するときには、いつでもサービスがスタートします。

Windows サービスからアンインストール(取り外し)する

サービスをアンインストールするには、 [UninstallMyApp-NT.bat]バッチファイルを実行してください。 もし現在、サービス動作中の場合には、まずそのサービスを停止してから実行されます。

コマンドと出力例:
UninstallMyApp-NT.bat
wrapper  | サービスは動作しています。停止中...
wrapper  | 停止の待機中...
wrapper  | My Application が停止されました。
wrapper  | My Application サービスを取り外しました。

コマンドベースのバッチファイル

UNIX ベースの OS からポートを利用するような一部のアプリケーションでは、 サービスのコントロールに UNIX 形式のコマンドスクリプトを使った方が、動作が良いこともあります。 コマンドベースのバッチファイルは、個別の専用バッチファイルの全ての機能を統合し、 一つのファイルになっているため、パラメータとしてコマンドを扱えます。

バッチファイルを設定する

Wrapper 配布物の「%WRAPPER_HOME%\src\bin 」フォルダを覗くと、 バッチファイルテンプレート「AppCommand.bat.in」が見えます。

アプリケーションのbin」フォルダにバッチファイルを単純にコピーしてご利用ください。 ファイル名の「App」部分をアプリケーション名に変更して、 ファイル名の拡張子「.in」を削除してください。

ファイル名の変更例:
MyServerCommand.bat.in             -> MyServerCommand.bat
MyServer.bat.in   -> MyServer.bat

全てのファイルの先頭に、アプリケーションのディレクトリー構造やファイル名に合わせてカスタマイズできるセクションが含まれています。

スクリプトのコンフィギュレーション部分:
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 -----------------------------------------------------------------------------

スクリプトを実行する

コマンドベースのバッチファイル自身に説明が含まれており、 ユーザーが何もパラメータを付けずに、スクリプトを動かしてみた場合、使い方が表示されます。

_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.
_PASS_THROUGH を無効にした使い方:
Usage: TestWrapperCommand [ console : start : stop : restart : pause : resume : status : permissions : privileges : install : installstart : update : remove : setup : teardown ]

...

Windows 用のバッチファイルには、UNIX スクリプトと少し違いがあります。 UNIX スクリプトは、コンソールで動作している Wrapper を停止するために使うことができますが、 Windows 用のバッチファイルでは不可能です。 さらに加えて、dump]コマンドは、Windows 用のバッチファイルにはありません。

ご覧のとおり、コマンドベースのバッチファイルは、幅の広い能力を提供しています:

一例として、次のコマンドを利用して、コンソールで Wrapper を開始できます:

MyApp.bat console
wrapper  | --> Wrapper がコンソールとして開始しました
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  |   {licensee} へライセンスを割り当て
wrapper  |
wrapper  | JVM 起動中...
jvm 1    | WrapperManager: 初期化中...

他のコマンドを実行するには、単純にconsole」コマンドを、実行したいコマンドに書き換えてください。

スタンドアローンバイナリ

Java Service Wrapper は、バッチファイルを利用せずに、直接、動作させることもできます。

Wrapper の使い方

もし、パラメータを付けずに、あるいは、-?を付けて 「wrapper」実行ファイルを実行すると、 以下のように、使い方の出力が表示されます。

Wrapper の使い方:
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.]

アプリケーションを開始する

コンソールアプリケーションとして Wrapper を動かすために、 「wrapper.conf」ファイルに続いて、 -c]コマンドを指定する必要があります。 「wrapper.conf」ファイルの配置場所は、絶対パスか相対パスで設定することができます。 もし、相対パスが利用されている場合、そのパスは、カレントディレクトリーではなく、 常に「wrapper.exe」ファイル場所への相対参照です。

コマンド例:
wrapper.exe -c ..\conf\wrapper.conf

サービスとしてアプリケーションをインストールする

アプリケーションを Windows サービスとしてインストールするためには、 以下の[-i]コマンドを実行します:

コマンド例:
wrapper.exe -i ..\conf\wrapper.conf

サービスとしてアプリケーションを開始する

一旦インストールされると、そのサービスは、他の Windows サービスと同じようにスタートします。 もし、[wrapper.ntservice.starttype]が AUTO_START」(自動スタート)に設定されている場合、 インストールされたとき、次回のマシン再起動時にサービスがスタートします。 サービスコントロールパネル([コントロールパネル]→[システムとセキュリティ]→[管理ツール]→[サービス])でサービスを選択し、サービスを開始ボタンをクリックたり、或いは、以下のコマンドを一つ実行することでサービスを開始できます。

コマンド例:
wrapper.exe -t ..\conf\wrapper.conf
net start MyApp

注意

net start x]や[net stop x]コマンドは、 開始や停止に時間を要するサービスでは問題があります。 ほとんどのケースで動作はしますが、もしサービスが停止するのに2、3秒かかる場合、まだ停止プロセスの途中であっても 「net stop x」コマンドは「サービスが停止されていた」と返してきます。 これでは、処理前にサービスが本当に停止されるまでスクリプトが待機しなければならない状況で、問題になります。 そこで、サービスの開始や停止に Wrapper を利用すれば、そのような問題を確実に回避することができます。

wrapper.conf」ファイル以外、 他のどこかに存在するような、インストールされているサービスの実際の名前を要求しないため、 スクリプトを使ったサービス開始や停止をする Wrapper 手法は便利です。 そのため、もしサービス名が変更されても、複数のファイルを手作業で編集する必要がありません。

サービスとしてアプリケーションを停止する

Windows でサービスを停止するには、サービスコントロールパネル ([コントロールパネル]→[システムとセキュリティ]→[管理ツール]→[サービス])で サービスを選択して「サービスの停止」をクリックするか、 あるいは、次のコマンドのどちらかを実行します:

コマンド例:
wrapper.exe -p ..\conf\wrapper.conf
net stop MyApp

サービスからアプリケーションをアンインストール(取り外し)する

アプリケーションを Windows サービスからアンインストールするには、次の[-r]コマンドを実行します:

コマンド例:
wrapper.exe -r ..\conf\wrapper.conf

もし、サービスのアンインストール時に、そのサービスが実行中であっても、キレイに停止して、サービスからアンインストールされます。

サービスとしてのアプリケーションのステータスを問い合わせする

Wrapper に、コマンドラインから、あるいは、バッチファイを使って、 サービス状況の問い合わせをすることができます。 これは、現在のサービス状況を知る必要がある Install スクリプトを利用する際に便利です。

コマンドと出力例:
wrapper.exe -q ..\conf\wrapper.conf
wrapper  | The My Application Service is installed.
wrapper  |   Start Type: Automatic
wrapper  |   Interactive: Yes
wrapper  |   Running: No

もし[-q]コマンドで動かすと、Wrapper は現在のステータスをコンソールに表示します。 [-qs]コマンドでは静かに動作します。 Wrapper は、次の「終了コード」ビットの組み合わせで終了します:

例えば、終了コード「15」(=1+2+4+8)では、『サービスがインストールされ、動作し、インタラクティブであり、 システムの起動時に、自動的にスタートするように設定されている』ということを示しています。 終了コード「0 (ゼロ)」では、『サービスが現在インストールされていない』という意味を表します。

参照: Wrapper でアプリケーションを起動する