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では、登録されたシャットダウンクラスのメインメソッドが完了するまでです。 インテグレーション方法３ 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］キー操作がトラップされました。  シャットダウン中。
jvm 1    | Starting MyApp shutdown...
jvm 1    | ...
jvm 1    | MyApp shutdown complete.
wrapper  | <-- Wrapperが停止しました

UNIX:

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

...
wrapper  | INTがトラップされました。  シャットダウン中。
jvm 1    | Starting MyApp shutdown...
jvm 1    | ...
jvm 1    | MyApp shutdown complete.
wrapper  | <-- Wrapperが停止しました

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

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

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

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

ほとんどのユーザーはこの［CTRL］＋［C］キー操作を好むことと思いますが、 もし常にJVMにキレイにシャットダウンする機会を確実に持たせたいと希望する場合には、 Wrapperバージョン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    | Starting MyApp shutdown...
jvm 1    | ...
jvm 1    | MyApp shutdown complete.
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］クラス の完全なJavadoc解説をご覧ください。

クライアントから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  | フィルタートリガーが一致しました。 シャットダウン中。
jvm 1    | 停止中...
wrapper  | <-- Wrapperが停止しました

フィルター以外にも、多くの機能があり、実行するアクションを指定することができます。 それらは全て、［SHUTDOWN］アクションを指定することができます。 例えば、次のプロパティです： ［wrapper.on_exit.<n>］、 ［wrapper.timer.<n>.action］、 ［wrapper.check.deadlock.action］、 ［wrapper.event.<event_name>.command.block.action］