方法1 - WrapperSimpleApp インテグレーション(Linux / UNIX)

概要

まず方法1は、アプリケーションの起動に[WrapperSimpleApp] ヘルパークラスを使う手法です。 これは遥かに簡単なインテグレーション方法で、利用が可能であれば、一番お薦めの手法です。

この方法を利用するにおいて理解しておくべき点がいくつかあります。 Wrapper が JVM をシャットダウンする際に、直接アプリケーションへシャットダウンをリクエストするわけではなく、 JVM 内部から[System.exit()]メソッドを呼び出して JVM のシャットダウンシーケンスに入ります。 もし、アプリケーションがシャットダウンフックを登録されている場合、通常どおりに実行処理され、 アプリケーションがキレイにシャットダウンできる時間を確保します。 その一方、もしシャットダウンフックを登録されていない場合、 コンソール(コマンドウィンドウ)から[CTRL]+[C]のキー操作によるアプリケーション任意停止と同じように動作し、アプリケーションを直ちに終了させます。 シャットダウンフックの有無に関わらず、いずれのケースでも、Wrapper 導入前の環境状態と同じように動作します。

この方法1でインテグレーションすると、WrapperSimpleApp]ヘルパークラスがアプリケーションのメインクラスを置き換えます。 これにより、[WrapperSimpleApp]クラスが、 即時に WrapperManager を初期化する機会を持つことができ、JVM を Wrapper に登録します。 [WrapperSimpleApp]クラスは、アプリケーションのライフサイクル(稼働状況)はもちろんのこと、 Wrapper との全ての対話を管理します。 WrapperManager 経由で Wrapper がスタートメッセージを JVM に送ると、 アプリケーションの本来のメインクラスのメインメソッドが呼び出されます。

アプリケーションのメインクラス名を引き渡すことで、どのようにアプリケーションを起動するのか、 [WrapperSimpleApp]ヘルパークラスへ指示が渡され、 [WrapperSimpleApp]のメインメソッドへのその他の追加的なアプリケーションパラメータが続き、進んでいきます。

操作方法の詳細

このセクションでは、さらに詳細に踏み込み、Wrapper 内で動かすためにはどうするのか、 シンプルな HelloWorld アプリケーションの設定方法を例にあげて説明します。 その他のほとんどのアプリケーションは、同様の手順でインテグレーションすることができます。

HelloWorld アプリケーション

ここでの解説は、「Hello world」を出力する、シンプルな HelloWorld アプリケーションの開始方法を説明します。 このアプリケーションへのパスは /usr/lib/helloworld で、 こちらでは{MYAPP_HOME}として参照します。 いくつかの追加フォルダー(「bin」、「lib」、「conf」、「logs」)の存在がが必要で、そちらへ Wrapper からのファイルがコピーされます。

Wrapper ファイルをインストールする

Wrapper を使えるようにするために4つのディレクトリーを操作する必要があります。

注意

動作しているプラットフォーム用にビルドされた適切なバージョンの Wrapper と 「libwrapper.so」ファイルであることを確認してください。 例えば、Wrapper の Linux 版は、Solaris 上では動作しません。

「bin」ディレクトリー

Wrapper には、シェルスクリプト[sh]が同封され、 Java Service Wrapper によって制御されているあらゆる Java アプリケーションを確実に起動および停止するために使用できます。

まず始めに、以下のファイルを HelloWorld の 「bin」ディレクトリーにコピーしてください。(Wrapper の旧バージョンのファイル名:「sh.script.in」)

{WRAPPER_HOME}/bin/wrapper
{WRAPPER_HOME}/src/bin/App.sh.in

アプリケーション名を反映してスクリプトファイル名を変更します。

{MYAPP_HOME}/bin/helloworld

次に、エディターで、そのスクリプトを開きます。 HelloWorld を起動する際のスクリプトで表示が反映されるように、ロング名(長い形式)やショート名(短い形式)を設定が必要です。 スクリプトのヘッダーの直後に、2つの変数 [APP_NAME]と [APP_LONG_NAME]が見えるでしょう。 この変数の推奨された値は次のとおりです。

APP_NAME="helloworld"
APP_LONG_NAME="Hello World"

スクリプトは何も追加変更を必要としませんが、コンフィギュレーションファイル 「wrapper.conf」が 一つ上の階層 ../conf/wrapper.conf にある 「conf」ディレクトリーにあるという前提で進めていきます。 もし、その「wrapper.conf」ファイルを他の場所に設置したい場合には、 「WRAPPER_CONF」の変数を適切に設定変更する必要があります。

注意

重要! 処理を進める前に、 「bin」ディレクトリーにコピーした全てのファイルが、 実行可能フラグが付いていることを確認してください。

「lib」ディレクトリー

ネイティブライブラリーと Wrapper jar ファイルを HelloWorld の lib ディレクトリーへコピーしてください。

{WRAPPER_HOME}/lib/libwrapper.so
{WRAPPER_HOME}/lib/wrapper.jar

libwrapper.so」ファイルは、 ネイティブライブラリーファイルであり、 JVM 内で動作する Wrapper の部分に必要なものです。 「wrapper.jar」ファイルには、全ての Wrapper クラスが含まれています。

注意

プラットフォームによっては、「ネイティブライブラリ」の命名規則が若干異なることに注意してください。 可能な名前は、 「libwrapper.a」、 「libwrapper.sl」、 「libwrapper.so」と 「libwrapper.jnilib」を含みます。 いずれにせよ、拡張子を変更せずにファイルをコピーする必要があります。

「conf」ディレクトリー

Wrapper では各アプリケーション用の設定ファイル(コンフィギュレーションファイル 「wrapper.conf」)が必要です。 その設定ファイルの標準配置ディレクトリーは、 アプリケーションホームディレクトリー下の「conf」ディレクトリーです。 以下の設定ファイルテンプレート「wrapper.conf.in」を HelloWorld の「conf」ディレクトリーにコピーしてください。

{WRAPPER_HOME}/src/conf/wrapper.conf.in

ファイル名の「.in」拡張子を外して、 ファイル名を「wrapper.conf」へ変更します。

以下のようになるはずです:

{MYAPP_HOME}/conf/wrapper.conf

もしコンフィギュレーションファイル「wrapper.conf」 の配置場所を変更したい場合には、自由に変更して構いませんが、新しい場所が反映されるように、 上記の「bin」ディレクトリーの中にコピーしたスクリプトを変更する必要があります。

「logs」ディレクトリー

デフォルトのコンフィギュレーションファイル 「wrapper.conf」は、 アプリケーションホーム下にある「logs」ディレクトリーの中に 「wrapper.log」ファイルを配置します。

ディレクトリーを作成したことを確認してください。

{MYAPP_HOME}/logs

もし「wrapper.log」ファイルを他の場所に配置したい場合には、 「wrapper.conf」ファイルを編集して、新しい場所が反映されるように [wrapper.logfile] プロパティを変更する必要があります。

「lang」ディレクトリー

Wrapper バージョン 3.5.0 より、 Wrapper をローカライズすることができます。 言語リソースファイルは、 「lang」ディレクトリーにあります。 必要があれば、アプリケーションのホームディレクトリー下に自分で 「lang」ディレクトリーを作成して、その中に言語リソースファイルをコピーしてください。

{MYAPP_HOME}/lang/wrapper_XX.mo
{MYAPP_HOME}/lang/wrapperjni_XX.mo

もし言語リソースファイル「*.mo」を他の場所に配置したい場合には、 「wrapper.conf」ファイルを編集して、新しい場所が反映されるように [wrapper.lang.folder] プロパティを変更する必要があります。

アプリケーションの Java コマンドラインの配置

Wrapper がアプリケーションを起動できるように Wrapper の設定を変更する前に、通常使う完全な Java コマンドを知っておく必要があります。

ほとんどのアプリケーションでは、スクリプトを活用し、実際のコマンドラインを操作します。 一般的に、ほとんどのスクリプトは、扱いにくい傾向にありますが、実際のところ、Wrapper の優れた機能により、 それらのスクリプトと無関係に動かすことができるのも、Wrapper メリットの一つなのです。

スクリプトの大部分には、システム固有の情報を収集して、その情報を環境変数の中に格納するタスク機能を備えています。 上記の行を明記することにより、収集した全ての情報を最終の Java コマンドへと拡張させ、それでアプリケーションを起動させることになります。

Wrapper の設定で、本当に必要な個所は、その最後の Java コマンドラインなのです。

私たちのシンプルな HelloWorld アプリケーションの場合、スクリプトは不要です。 起動するためのコマンドは次の通りです。

java com.tanukisoftware.HelloWorld

Java アプリケーションを起動するためのより複雑なコマンドは、次のようになります。

java -classpath "/usr/lib/helloworld/lib/myjar.jar" -Xms128M -Xmx512M com.tanukisoftware.HelloWorld arg1 arg2

コンフィギュレーションファイル「wrapper.conf」の変更

上記のコマンドラインを Wrapper で使うためには、そのコマンドラインのコンポーネントを細分化して、 コンフィギュレーションファイルへ落とし込んでいく必要があります。 「wrapper.conf」 ファイルをエディターで開き、下記のようにプロパティに変更を加えてください。

注意

下記の文中で説明しているプロパティについて、そのリンク先では、それぞれ詳しい説明を提供しています。 じっくり時間をかけて、変更するプロパティの説明を全部、熟読してください。 多くのケースでは、ここでは触れていない事項についても、さらに詳しい使い方の説明があります。

環境変数:

コンフィギュレーション設定を容易にするために、HelloWorld と Java の HOME ディレクトリーの 環境変数を設定して、 その変数をコンフィギュレーションファイルに書き込むことを推奨します。 これで、コンフィギュレーションファイルが読みやすくなり、さらにディレクトリーパスの変更などのメンテナンスにも好都合です。 一旦設定すると、Java Service Wrapper は、毎回の起動ごとに環境変数を設定します。

set.MYAPP_HOME=/usr/lib/helloworld
set.JAVA_HOME=/usr/lib/jvm/java-8-openjdk

Java 実行ファイル

まず、Java 実行ファイルを解凍して、その配置場所のパスを [wrapper.java.command] プロパティにへ割り当てます。

wrapper.java.command=%JAVA_HOME%/bin/java

Java 引数

ほとんどのアプリケーションは、起動時に Java 実行ファイルへ数多くのパラメータを提供します。 Wrapper では、クラスやライブラリーパス同様にメモリのような物事を設定するのために特別なプロパティを提供しています。 これについては後で述べますが、その他の設定は、 [wrapper.java.additional.<n>] シリーズのプロパティを使って設定変更します。

HelloWorld アプリケーションには2つの追加 Java 引数が必要です。

wrapper.java.additional.1=-Xms128M
wrapper.java.additional.2=-Xmx512M

JVM の初期メモリや最大メモリサイズは「-Xms128M(初期)」「-Xmx512M(最大)」で指定されていますが、 [wrapper.java.initmemory]プロパティや [wrapper.java.maxmemory]プロパティを使って定義することができます。

# Initial Java Heap Size (in MB)
wrapper.java.initmemory=128

# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=512

Wrapper Jar

wrapper.jar」ファイルを指定する必要があります。

wrapper.jarfile=%MYAPP_HOME%/lib/wrapper.jar

警告

wrapper.jarfile]プロパティは、Wrapper ver. 3.5.55 で導入されました。 それより前の Wrapper バージョンを利用する場合、クラスパスに「wrapper.jar」を追加する必要があります。

wrapper.java.classpath.1=D:\apache-tomcat-9.0.0.M13\lib\wrapper.jar

そして、[wrapper.java.classpath.1]プロパティが重複しないように、次のクラスパス要素のインデックスを調整する必要があります

クラスパス

次にクラスパスです。 [wrapper.java.classpath.<n>] プロパティを使って設定を変更します。 Wrapper では、クラスパスを個別のエレメントへ細分化する必要があります。

wrapper.java.classpath.1=%MYAPP_HOME%/bin/myjar.jar

メインクラス

HellowWorld と Wrapper との間の通信を設定するにはメインクラスとして[WrapperSimpleApp]を設定する必要があります。 起動時に Java によって実行されるこのメインクラスは、 [wrapper.java.mainclass] プロパティを使って指定します。 HelloWorld のメインクラスは、次のとおり最初のアプリケーションパラメータとして指定します。

wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperSimpleApp

アプリケーションパラメータ

アプリケーションパラメータは、 [wrapper.app.parameter.<n>] プロパティを使って設定します。 アプリケーションパラメータは、メインクラスの後、Java コマンドラインに直接表示されます。 上記で述べたように、その最初のパラメータは実行している HelloWorld のメインクラス名なのです。 その他のパラメータはすべてそのあとに設定します。

wrapper.app.parameter.1=com.tanukisoftware.HelloWorld
wrapper.app.parameter.2=arg1
wrapper.app.parameter.3=arg2

ライブラリーパス

Wrapper を使うために、設定しなければならないプロパティがもう一つあります。 システムとの対話をコントロールするため、Wrapper は、ネイティブライブラリーを利用します。 このライブラリーファイルlibwrapper.so」は、 JVM へ供給されるライブラリーパスで指定しておく必要があります。

ライブラリーパスは、 [wrapper.java.library.path.<n>] プロパティを使って設定します。

wrapper.java.library.path.1=%MYAPP_HOME%/lib

全部をまとめる

全部をまとめると、下記のようになります:

set.MYAPP_HOME=/usr/lib/helloworld
set.JAVA_HOME=/usr/lib/jvm/java-8-openjdk

wrapper.java.command=%JAVA_HOME%/bin/java

# Java Main class.
wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperSimpleApp

# Wrapper Jar
wrapper.jarfile=%MYAPP_HOME%/lib/wrapper.jar

# Java Classpath
wrapper.java.classpath.1=%MYAPP_HOME%/bin/myjar.jar

# Java Library Path (location of Wrapper.DLL or libwrapper.so)
wrapper.java.library.path.1=%MYAPP_HOME%/lib

# Java Bits.  On applicable platforms, tells the JVM to run in 32 or 64-bit mode.
wrapper.java.additional.auto_bits=TRUE

# JVM settings
wrapper.java.additional.1=-Xms128M
wrapper.java.additional.2=-Xmx512M

# Initial Java Heap Size (in MB)
#wrapper.java.initmemory=128

# Maximum Java Heap Size (in MB)
#wrapper.java.maxmemory=512

# Application parameters. Add parameters as needed starting from 1
wrapper.app.parameter.1=com.tanukisoftware.HelloWorld
wrapper.app.parameter.2=arg1
wrapper.app.parameter.3=arg2

試しに動かしてみる

ここまで来れば、単純に「bin/helloworld console」スクリプトを実行することで HelloWorld を動かすことができます。 Wrapper がカレントディレクトリーを設定してくれるお陰で、 「bin」ディレクトリー内部から、このスクリプトを実行する必要はありません。

ご覧のとおり、コマンドを省略すると、Wrapper に同梱して提供しているスクリプトは、極めて標準的なデーモンスクリプトで、 console]、[start]、[stop]、 [restart]と[dump]コマンドを受け付ます。 start]、[stop]と[restart] コマンドは、ほとんどのデーモンスクリプトでは一般的なもので、 Wrapper や、デーモンプロセスとしてのアプリケーションをコントロールするために使われます。 status]コマンドは、Wrapper が現在稼働中かどうか検知するために使われます。 console]コマンドは、カレントシェル内で、Wrapper を起動し、 [CTRL]+[C]のキー操作でアプリケーションを任意停止することを可能にします。 最後のdump]コマンドは、JVM にフルスレッドダンプをさせるように仕向けるために、 Wrapper へ「kill -3」シグナルを送ります。

おめでとう!あなたのアプリケーションが起動して動き始めるはずです。

もし何か問題があった場合、トラブルシューティングをご覧いただき、 問題点を追究するのに役立つことでしょう。

上級者向け

スタートアップを調整する

デフォルトでは、[WrapperSimpleApp] クラスは2秒間待機して、ユーザーアプリケーションのメインメソッドの確立を待ちます。 その後、アプリケーションがスタートしたものとして解釈して、Wrapper プロセスに戻ります。 これは、多くのユーザーアプリケーションが応答を返してこないメインメソッドで書かれているため、そのように処理を進めています。 そのようなケースでは、アプリケーションが無事にスタートアップしたのか、スタートアップが完了したのか言及できず、 [WrapperSimpleApp]クラスにとっては頼れる手段がありません。

しかしながら、もし、アプリケーションのメインメソッドが、アプリケーションの開始応答を一旦戻してくる場合には、 Wrapper にとっては理想的なことであり、Wrapper は継続せず、アプリケーションの起動が確立するまで待機します。

waitForStartMain システムプロパティ:

このように応答を返してくるメインメソッドに対しては、[WrapperSimpleApp]が [org.tanukisoftware.wrapper.WrapperSimpleApp.waitForStartMain] システムプロパティを探し、もし「TRUE」に設定されていた場合、 [WrapperSimpleApp]はアプリケーションのメインメソッドが完了するまで 無期限に待機します。

設定例:(待機あり)
wrapper.java.additional.10=-Dorg.tanukisoftware.wrapper.WrapperSimpleApp.waitForStartMain=TRUE

maxStartMainWait システムプロパティ:

タイミング良くメインメソッドが応答を返してくることが確実に分かっている場合には、この『無期限の待機』のオプション設定は 有意義な選択肢となるでしょう。 しかし、スタートアップ処理でどんなに時間がかかろうが、Wrapper は待機中に決してギブアップすることはなく、ひたすら待ち続けるでしょう。

もしスタートアップでハングアップする可能性を考えると、 その[org.tanukisoftware.wrapper.WrapperSimpleApp.maxStartMainWait] システムプロパティのオプション設定で「待機時間のタイムアウト(時間切れ)」を設定しておくのが良いと思います。 スタートアップメインメソッドの起動確立に5分間(300 秒間)まで待機させるには、以下のようにプロパティを「300」に設定してください。

デフォルト値は「2秒です。

設定例:(300 秒)
wrapper.java.additional.10=-Dorg.tanukisoftware.wrapper.WrapperSimpleApp.maxStartMainWait=300

注意

多くのアプリケーションのメインメソッドでは応答を返してこない設計になっています。 その場合、デフォルト値2秒のスタートアップのタイムアウトをそのまま利用するか、 あるいは、アプリケーションのスタートアップに要する時間数を測定して、 やや長めのタイムアウト時間を[maxStartMainWait] プロパティを使って指定するか、どちらかを必ず選ばなくてはなりません。

警告

スタートメソッド(startが応答を返してこないアプリケーション用に、 [waitForStartMain]を「TRUE」に設定した場合、 Wrapper は一見、正しく動作しているように見えるかもしれませんが、実は Wrapper はエンドレスで永久に待機状態であり、 決して稼働状態に入ることはなく、アプリケーションを監視しない、ということです。