Java 1.3から、Java には特別なスレッド「シャットダウンフック」を登録する機能が 導入され、シャットダウン準備が整ったときに JVM が実行するものです。 シャットダウンフックがない場合、アプリケーションはシャットダウンされることを知る手段がありません。 ゆえに、「進行中の作業を完了して、保存する必要性のあるデーターを保存する」という必要な処理を進めることができません

ここでは、シャットダウンフックについての詳細には踏み込みませんが、 シャットダウンフックがどのようなもので、JVM に登録する方法を示す簡単な例を次に示します。

シャットダウンフックを登録する：

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 );

複数のシャットダウンフックを登録することは可能であり、一般的なことです。 通常、各アプリケーションや主要コンポーネントは、必要に応じて独自のシャットダウンフックを登録します。 シャットダウンフックの登録は、シャットダウンのタイミングに関係なく正しく処理されるように、 初期化処理の一部として行われるべきです。 ほとんどのケースで、シャットダウンフックを登録すれば、あとは登録したことを忘れてしまっても大丈夫です。

シャットダウンフックを登録解除する：

そうせずに、シャットダウンフックのコードを書くことも、通常、可能ですが、 どこかの時点で、シャットダウンフックを登録解除する必要性がある場合、以下のようにしてください。

Runtime.getRuntime().removeShutdownHook( shutdownHook );

JVM シャットダウン：

JVM がシャットダウンを開始するとき、登録された全てのシャットダウンフックをループオーバーして、 新しいスレッドとして、それぞれを起動します。 そのシャットダウンフックスレッドは、全てが完了するまで、並行して動作します。 最後のシャットダウンフックが完了すると、JVM は何か他の動作中のスレッドがあれば停止させて、すぐに終了します。

jvm 1    | Starting MyApp shutdown...
jvm 1    | ...
jvm 1    | MyApp shutdown complete.
wrapper  | <-- Wrapper が停止しました

シャットダウンフックの１つの問題は、内部的に完了するまでに時間を要するということです。 この時間中に、通常は、Java に早くシャットダウンするように伝える手段がありません。 この問題の回避策として、Wrapper では設定可能な「JVM Exit タイムアウト」を利用しています

Java Service Wrapper で統合した JVM シャットダウンを開始すると、 JVM はWrapper の内部シャットダウンフックを実行します。 Wrapper は自分のシャットダウンフック機能を利用して、 Wrapper でラップされたアプリケーションをキレイにシャットダウンするように働きかけ、最後にクリーンアップします。

多くのユーザーと同じように、 インテグレーション方法１（WrapperSimpleApp）あるいはインテグレーション方法４（WrapperJarApp） を使用する場合、Wrapper のシャットダウンフックはほとんど即座に完了します。

しかしながら、もしインテグレーション方法２ (WrapperStartStopApp)や インテグレーション方法３ (WrapperListenerカスタマイズ)を利用する場合には、 Wrapper のシャットダウンフックは、アプリケーションが停止するまで動作します。 インテグレーション方法２（WrapperStartStopApp）の場合、 登録された shutdown クラスのメインメソッドが完了した時です。 インテグレーション方法３（WrapperListener）実装の場合、WrapperListener.stop()メソッドが完了した時点となります。

Wrapper では、Wrapper シャットダウンフックが完了するまでに許容される最大時間を示す シャットダウンタイムアウトを定義しています。 もし Wrapper のシャットダウンが「タイムアウト時間内に完了した」報告が失敗すると、 Wrapper は「シャットダウンプロセスがフリーズ（凍結）した」と想定して、強制的に JVM を終了させます。 これは、アプリケーションが不安定な状態で残ってしまうという問題の回避策として行われています。 シャットダウンタイムアウトのデフォルト値は「３０秒」で、 ［wrapper.shutdown.timeout］プロパティを使って設定します。

jvm 1    | 停止中…
wrapper  | シャットダウン失敗: JVM からのシグナル待ちのタイムアウト。
wrapper  | JVM はリクエストに応じて終了しませんでした、中止しました
wrapper  | <-- Wrapper が停止しました

Wrapper のシャットダウンフックが完了して、Wrapper が「JVM のシャットダウン準備ができた」通知を受けた後、 Wrapper は単純に、JVM自身が終了するまで待機モードに入ります。 JVM は登録された全てのシャットダウンフックを並行して起動しますので、覚えておいてください。 それは最後のシャットダウンフックが完了して終了するまで待機します。 もし、どれか他のシャットダウンフックが完了するまでに時間を要する場合、これもしばらく時間がかかるでしょう。 上記で述べたシャットダウンタイムアウトのように、 アプリケーションが有効でない状態に陥るのを避けるために、しばらくした後に、 タイムアウトするように Wrapper は設計されています。 このタイムアウトのデフォルト値は「１５秒」で、 ［wrapper.jvm_exit.timeout］プロパティを使って設定します。

jvm 1    | 停止中…
jvm 1    | 停止しました。
wrapper  | シャットダウン失敗： 終了する JVM 待ちのタイムアウト。
wrapper  | JVM はリクエストに応じて終了しませんでした、中止しました
wrapper  | <-- Wrapper が停止しました

最後のシャットダウンフックが完了すると、JVMプロセスは、ほぼ即座に終了するはずです。 終了プロセスに時間を要する原因の１つで分かっていることは、JVM ヒーププロファイリングが有効で、 ダンプファイルが保存されている時です。

対応バージョン :	1.0.0
対応エディション :
対応プラットフォーム :

ほとんどのユーザーがする最初の方法は、Wrapper がコンソールやタ−ミナルで動作中に、 単純な［CTRL］＋［C］キー操作です。 この方法には、何も特別な開発に影響するような要件がなく、ほとんどのアプリケーションで利用することができます。 この方法は特別な開発を必要とせず、ほぼすべてのアプリケーションで使用できます。

Windows：

Windows 上で、ユーザーが［CTRL］＋［C］キー操作をすると、 Wrapper はその終了リクエストを Java プロセスへ転送します。 その後、Java はアプリケーション内に登録されているすべてののシャットダウンフックを起動することでリクエストを処理します。

...
wrapper  | CTRL-C trapped.  Shutting down［CTRL］＋［C］キー操作がトラップされました。  シャットダウン中。
jvm 1    | MyApp シャットダウン開始中…
jvm 1    | ...
jvm 1    | MyApp シャットダウン完了。
wrapper  | <-- Wrapper が停止しました

UNIX：

UNIX プラットフォームで［CTRL］＋［C］キー操作をすると、「INT」シグナルが Wrapper へ送信されます。 そのため、やや異なるように見える出力が発生します。

...
wrapper  | がトラップされました。  シャットダウン中。
jvm 1    | MyApp シャットダウンを開始中…
jvm 1    | ...
jvm 1    | MyApp シャットダウン完了。
wrapper  | <-- Wrapper が停止しました

［CTRL］＋［C］キー操作：

アプリケーションを開発しているとき、アプリケーションがキレイにシャットダウンするまで常に待機するのが面倒になる場合があります もし本当に即座にシャットダウンしたい場合、Wrapper では、JVM を終了させるために２回目の ［CTRL］＋［C］キー操作を利用できます。 これはとても便利ですが、シャットダウンフック動作が完了しなかったために、 データを正しく保存できない可能性がある、という欠点があります。

...
wrapper  | ［CTRL］＋［C］キー操作がトラップされました。  シャットダウン中。
jvm 1    | MyApp シャットダウン開始中…
wrapper  | ［CTRL］＋［C］キー操作がトラップされました。即時にシャットダウンを強制中。
wrapper  | JVM はリクエストに応じて終了しませんでした。中止しました
wrapper  | <-- Wrapper が停止しました

［CTRL］＋［C］キー操作の無効化：

ほとんどのユーザーはこの［CTRL］＋［C］キー操作を好むと思われますが、 もし常に JVM にキレイにシャットダウンする機会を確実に持たせたいと希望する場合には、 Wrapper ver. 3.5.15 から導入された ［wrapper.disable_forced_shutdown］ プロパティを利用して、即座にシャットダウンする機能を無効にすることができます。

また、内部的にユーザーが［CTRL］＋［C］キー操作でアプリケーションを停止できないように意図的にしたい場合もあります。 その場合には、［wrapper.ignore_signals］プロパティを利用して、簡単に設定することができます。 当然ながら、もし、そのように設定した場合、アプリケーションをシャットダウンする他の手法が必要になりますので、ご注意ください。

wrapper  | ［CTRL］＋［C］キー操作がトラップされましたが、無視しました。

対応バージョン :	1.0.0
対応エディション :
対応プラットフォーム :

UNIX プラットフォーム上で、Wrapper プロセスへ「TERM」シグナルを送信することが可能です。 実際のところ、これは、Wrapper に同梱しているシェルスクリプトのデフォルトでシャットダウンするリクエストの処理方法です。

「TERM」シグナルは、上記で述べた ［">CTRL］＋［">C］キー操作方法のように、ほとんど正確に動作します。

...
wrapper  | TERM がトラップされました。  シャットダウン中。
jvm 1    | MyApp シャットダウン開始中…
jvm 1    | ...
jvm 1    | MyApp シャットダウン完了。
wrapper  | <-- Wrapper が停止しました

コマンドラインから、次のコマンドで、このシグナルを送信することができます。

kill {pid}

「{pid}」部分は、Wrapper のプロセス ID で置き換えてください。 もし、これをプログラム的に行いたい場合、［wrapper.pidfile］プロパティを使って、 pid ファイルにそのカレントプロセス ID を保存するように Wrapper を設定することができます。 もし、Wrapper シェルスクリプトを利用している場合、このファイルはデフォルトで Wrapper バイナリと同じディレクトリーに存在しています。

同様に［wrapper.ignore_signals］プロパティで、 この種類のシャットダウンを無効にすることができます。

wrapper  | TERM がトラップされましたが、無視しました。

対応バージョン :	1.0.0
対応エディション :
対応プラットフォーム :

Windows サービスとして実行している場合、いくつかのコマンドのいずれかを使用してサービスを停止することが可能です。

• まず１つ目は、サービスコントロールパネルでサービスを停止することです。 （［コントロールパネル］→［管理ツール］→［サービス］）
• ２つ目は、コマンドラインで「net」コマンドを利用します。

net stop myapp

• ３つ目は、コマンドラインで「sc」コマンドを利用します。

sc stop myapp

どのコマンドのケースでも、サービスを停止するようにリクエストを発信し、 Windows サービスコントロールマネージャーが、サービスシャットダウンプロセスをコントロールし、 その処理が完了するとレポートを返してきます。 Wrapper は常に、JVM をキレイにシャットダウンする試みるをすることで、対応します。

jvm 1    | ...
jvm 1    | 停止中…
wrapper  | <-- Wrapper が停止しました

システム全体をシャットダウンするときは、シャットダウンの前に、OS により Wrapper がシャットダウンされます。 一部の Windows では、サービスがシャットダウンされているという報告を無視して、 サービス停止に長い時間を要している場合には、単純にサービスを終了させます。 この場合、Wrapper とその JVM が OS によって強制終了されたため、ログファイルが途切れることがあります。

wrapper  | ユーザーがログアウトしました。無視しました。
wrapper  | マシンがシャットダウンしています。
jvm 1    | 停止中…
wrapper  | <-- Wrapper が停止しました

対応バージョン :	3.1.1
対応エディション :
対応プラットフォーム :

［wrapper.anchorfile］プロパティを使って、 アンカーファイルを出力するように、Wrapper を設定することができます。 アンカー（錨）は、船が流れていなかように停泊させるために利用されます。 Wrapper も同じように、このファイルを利用します。 スタートアップ時にアンカーファイルを作成し、定期的にそのファイルの存在をチェックします。 もし、アンカーファイルが削除された場合には、Wrapper は即座にシャットダウンプロセスを開始します。

jvm 1    | ...
wrapper  | アンカーファイルが削除されました。 シャットダウン中。
wrapper  | <-- Wrapper が停止しました

UNIX 上で、システムシグナルを無視するようにシェルスクリプトを編集した場合には、 このアンカーファイルの手法を利用して、Wrapper がシャットダウンされるべきタイミングをコントロールします。

対応バージョン :	3.2.0
対応エディション :
対応プラットフォーム :

Wrapper が解釈できる多数のコマンドのいずれかを含むコマンドファイルを検索するように、Wrapper を設定することができます。 そのファイルの配置場所は、［wrapper.commandfile］プロパティを使って指定します。 そのプロパティは、デフォルトで、無効になっています。

コマンドは、単純なテキストファイルにコマンドを含めて簡単に作成して、実行することができます。 コマンドが処理されるとすぐに、Wrapper はそのコマンドファイルを削除します。

STOP

jvm 1    | ...
wrapper  | コマンド「STOP」。 終了コード「0」でシャットダウン中。
jvm 1    | 停止中…
wrapper  | <-- Wrapper が停止しました

もし、この方法を利用する場合には、もちろん、そのコマンドを発行することが許されているユーザーだけが操作できるように、 コマンドファイルを配置するディレクトリーを保護することが重要です。 有効なコマンドリストに関してや、いくつか使用例なども、 ［wrapper.commandfile］プロパティの解説をご覧ください。

対応バージョン :	3.0.4
対応エディション :
対応プラットフォーム :

Wrapper には、リモートで Wrapper をコントロールする Telnet クライアントで接続できるオプションクラスがついてます。 この方法を利用するには、アプリケーションに数行のコードを追記する必要があります。 「WrapperActionServer」 クラス の完全な Javadocs 解説をご覧ください。

クライアントが Wrapper をシャットダウンすることのみを許可する単純なサーバーをセットアップするには、次のコードを追加してみてください。

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

追加アクションは、 Javadocsに記述されている 適切なメソッドをコールすることで実行可能です。

一旦、この設定が終われば、コマンド「telnet localhost 9999」でアプリケーションへ接続することができます。 接続されたら、単純に「S」キー操作で、Wrapper がキレイにシャットダウンします。 これには内部的なセキュリティリスクがありますので、利用する際には、このポートを保護することを忘れないでください。 リスニングソケットを localhost にバインドすることも可能で、ゆえにリモート接続を阻止します。

対応バージョン :	1.0.0
対応エディション :
対応プラットフォーム :

結果として、あるいはテストの一環として、Wrapperプロセスを強制終了することを希望することもあるでしょう。 Windows上で、タスクマネージャーを開き、プロセスタブの「wrapper.exe」ファイルを探し、 ［プロセスを終了する］キー操作をすることで、強制終了することができます。 UNIX上で、「kill」コマンドの変数「kill -9 {pid}」 を利用して、同様に強制終了することができます。 両方のケースで、プロセスを間違えて終了しないよう、十分に注意する必要があります。

このように Wrapper プロセスを停止させると、即座に終了するため、JVM をキレイにシャットダウンする機会が失われます。 Java コンポーネントが自動的に Java シャットダウンプロセスを開始するように、Wrapper を設計してあります。 これは、JVM がコントロール不能のゾンビ（孤児）プロセスになってしまうのを避けるために、重要な処理です。

Wrapper が停止されると、Wrapper のログファイルもその瞬間に記録を停止します。 この時点以降、Java ログ出力はどれも、ログファイルに残りません。

対応バージョン :	1.0.0
対応エディション :
対応プラットフォーム :

Wrapper プロセスとかなり同様の手法で、Java プロセスを強制終了することができます。 念のため、これはテスト用として以外、通常、行うべきではありません。 ［wrapper.java.pidfile ］プロパティを使って、 Java プロセス ID を書き出すように Wrapper を設定することができます。

デフォルトで、JVM がこのように停止されると、Wrapper はクラッシュしたと想定して、新しい JVM でアプリケーションを再起動します。

jvm 1    | ...
wrapper  | JVM が予想外に終了しました。
wrapper  | JVM 起動中…
jvm 2    | WrapperManager: 初期化中…
jvm 2    | ...

もし、このように Java プロセスが終了すると、 そのシャットダウンフックを実行する機会がなく、ゆえにキレイにシャットダウンされません。

対応バージョン :	1.0.0
対応エディション :
対応プラットフォーム :

JVM 内部から JVM を停止するには、いくつか方法があります。 Wrapper の特別なコードを必要としない最も一般的な方法は、単純に「System.exit(0)」をコールすることです。 これが発生すると、JVM は、登録された全てのシャットダウンフックを含め、通常のシャットダウンプロセスを開始します。

jvm 1    | ...
jvm 1    | 停止中…
wrapper  | <-- Wrapper が停止しました

その終了メソッドの引数は、JVM の終了コードを指定するために利用します。 終了コードは、JVMを起動したアプリケーションに何が起こったかを理解させるのに非常に役立ちます。 Wrapper は異なる終了コードを識別することができ、希望するとおりに様々なアクションを起こすことができます。 詳しくは、［wrapper.on_exit.<n>］プロパティをご覧ください。

また、Java は「Runtime.getRuntime().halt(0)」を提供しており、 登録したシャットダウンフックを実行せずに、JVM　をシャットダウンすることが可能です。 一部のケースでこれは便利ですが、Wrapper にとって、JVM が意図的にシャットダウンされることを知る手段がないので、Wrapper 上では、この使用は推奨されません。 このように JVM が終了すると、Wrapper はJVMクラッシュや予想外の終了として解釈しますので、ゆえに JVM を再起動します。

jvm 1    | ...
wrapper  | JVM が予想外に終了しました。
wrapper  | JVM 起動中…
jvm 2    | WrapperManager: 初期化中…

もし、本当にシャットダウンフックを実行せずにシャットダウンの必要があるならば、 下記の「WrapperManager.stopimmediate(0)」メソッドをお試しください。

対応バージョン :	1.0.0
対応エディション :
対応プラットフォーム :

他の方法は、「WrapperManager.stop(0)」をコールすることで、Wrapper API を利用することです。 これが発生すると、JVM は、登録された全てのシャットダウンフックを含め、通常のシャットダウンプロセスを開始します。

jvm 1    | ...
jvm 1    | 停止中…
wrapper  | <-- Wrapper が停止しました

対応バージョン :	3.0.4
対応エディション :
対応プラットフォーム :

もし、登録されたシャットダウンフックを実行せずに JVM をシャットダウンしたいなら、 「WrapperManager.stopImmediate(0) 」メソッドをコールすることで実現できます。 これで、JVM がシャットダウンされる予定があることを Wrapper に知らせますが、シャットダウンフックを実行せずに行います。

jvm 1    | ...
wrapper  | <-- Wrapper が停止しました

対応バージョン :	3.0.0
対応エディション :
対応プラットフォーム :

Wrapper には、JVM コンソールログ出力上にフィルターを登録する機能を備えており、 フィルター条件に一致した場合に、アクションを実行します。 １つのアクションが［SHUTDOWN］です。 有効なアクションの種類など、詳しくは各ページ、 ［wrapper.filter.action.<n>］プロパティ、 ［wrapper.filter.trigger.<n>］プロパティをご覧ください。

何も Java コードを記述する必要はなく、アプリケーションに機能を追加することが可能になるため、フィルター機能は非常に強力です。 Wrapper コンフィギュレーションファイル内で全体にフィルターを設定することができます。

アプリケーションのログに文字「Oops」と記録された時にいつでも JVM をシャットダウンするには、次のようにプロパティを設定します。

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 が停止しました

フィルター以外にも、多くの機能があり、実行するアクションを指定することができます。 それらは全て、［SHUTDOWN］アクションを指定することができます。 これらはすべてSHUTDOWNアクションを指定することができます。 例としては、次のプロパティがあります。

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