インデックス

  • 環境変数の展開
  • 環境変数の定義
    • "set.<X>"
    • "set.default.<X>"
  • デフォルト環境変数の定義
    • [WRAPPER_ARCH]変数
    • [WRAPPER_BASE_NAME]変数
    • [WRAPPER_BIN_DIR]変数
    • [WRAPPER_BITS]変数
    • [WRAPPER_CONF_DIR]変数
    • [WRAPPER_EDITION]変数
    • [WRAPPER_FILE_SEPARATOR]変数
    • [WRAPPER_HOSTNAME]変数
    • [WRAPPER_INIT_DIR]変数
    • [WRAPPER_JAVA_HOME]変数
    • [WRAPPER_JAVA_VENDOR]変数
    • [WRAPPER_JAVA_VERSION]変数
    • [WRAPPER_JAVA_VERSION_MAJOR]変数
    • [WRAPPER_JAVA_VERSION_MINOR]変数
    • [WRAPPER_JAVA_VERSION_REVISION]変数
    • [WRAPPER_LANG]変数
    • [WRAPPER_OS]変数
    • [WRAPPER_PATH_SEPARATOR]変数
    • [WRAPPER_PID]変数
    • [WRAPPER_RUN_MODE]変数
    • [WRAPPER_VERSION]変数
    • [WRAPPER_WORKING_DIR]変数
  • 擬似環境変数の定義
    • [WRAPPER_PERCENTAGE]変数
    • [WRAPPER_RAND_NNNNNN]変数
    • [WRAPPER_SYSMEM_PP.P]変数
    • [WRAPPER_TIME_YYYYMMDDHHIISS]変数
  • イベントハンドラ変数の定義
    • [WRAPPER_NAME]変数
    • [WRAPPER_DISPLAYNAME]変数
    • [WRAPPER_DESCRIPTION]変数
    • [WRAPPER_EVENT_JVM_ID]変数
    • [WRAPPER_EVENT_JVM_PID]変数
    • [WRAPPER_EVENT_NAME]変数
    • [WRAPPER_EVENT_RAND_NNNNNN]変数
    • [WRAPPER_EVENT_TIME_YYYYMMDDHHIISS]変数
    • [WRAPPER_EVENT_WRAPPER_PID]変数

環境変数の展開

Wrapper は、いかなるプロパティ値でもランタイム時に、環境変数の展開をサポートしています。 コンフィギュレーションファイル 「wrapper.conf」の本質を活かし、 プラットフォームに依存しない独立型を意識して整備しておけば、 Windows のシンタックス(構造文法ルール)は、全てのプラットフォームに利用することができます。

Wrapper がサービスとして動かされる時、環境からではなく、 システムレジストリから環境変数がロード(読み込み)されます。 これは、Windows がマシンを起動するときに、サービスが利用する環境変数をロード(読み込み)するために必要です。 レジストリにあるシステム環境変数が変更(直に設定の変更やコントロールパネルを通しての変更)された場合、 マシンを再起動するまでサービスへ有効になりませんが、 レジストリから環境変数をロード(読み込み)することで、同じ機能を提供している間は、 再起動の必要性を避けることができます。

JAVA_HOME]環境変を参照している例:
wrapper.java.command=%JAVA_HOME%/bin/java

これは、[JAVA_HOME]環境変数を定義する、 いかなるシステム上においても、完全に適切なパスへ、ランタイムで展開します。

Windows で、[JAVA_HOME]:
wrapper.java.command=C:\Sun\jdk1.3\bin\java
UNIX で、[JAVA_HOME]:
wrapper.java.command=/opt/IBMJava2-131/bin/java

注意

もし参照される環境変数が定義されていない場合、警告がログに記録され、プロパティ値はそのままの状態で解釈されます。

Wrapper ver. 3.5.55 以降では、「#variables.expand」ディレクティブを使用して、コンフィギュレーションファイル内のセクションで変数の展開を無効にし、警告メッセージを回避することができます。

環境変数の定義

Wrapper は、コンフィギュレーションファイル 「wrapper.conf」 内部から、あるいは、 コマンドラインから、環境変数を定義する機能を備えています。 一旦、定義されれば、その環境変数は他の環境変数と同様に参照が可能です。 これは、上記で述べている変数の展開での利用も含みます。

「set.」、「set.default.」で始まる特別なプロパティ名:

冒頭に[set.]や[set.default.]を付加して 環境変数名を指定すると、新しい環境変数を定義することができます。 プロパティ値に環境変数名を指定すると、そのプロパティ値は指定した環境変数値で置き換えられます。

set.EXTERN_APP=C:/ExternAppHome

もし、[set.default.]で始まる変数名を使うと、 その環境変数はまだ存在していない時だけ、新しく環境変数が作成されます。 これはシリーズ化した環境変数のデフォルト値を定義するときに便利です。

set.default.EXTERN_APP=C:/ExternAppHome

設定例:

環境変数を定義する機能のお陰で、コンフィギュレーションファイルを介して利用される値を 簡単に変更することが可能です。 以下の例では、外部アプリケーションの配置場所を特定するために、 環境変数の使用方法を示しています。

set.EXTERN_APP=C:/ExternAppHome

wrapper.java.classpath.1=../lib/wrapper.jar
wrapper.java.classpath.2=%EXTERN_APP%/lib/jar1.jar
wrapper.java.classpath.3=%EXTERN_APP%/lib/jar2.jar
wrapper.java.classpath.4=%EXTERN_APP%/lib/ext/jar3.jar
wrapper.java.classpath.5=%EXTERN_APP%/lib/ext/jar4.jar

環境変数の定義の利用は、いつ、どのように、値を変更すれば良いのか理解していれば、とてもパワフルです。 Wrapper が起動される前に設定する環境変数は、もちろん、通常どおりに使うことができます。 もしコンフィギュレーションファイルに同じ変数名が指定されている場合には、 コンフィギュレーションファイルの値は、既存の値を上書きします。

コマンドラインによる変数定義:

コマンドラインから定義された環境変数は、少し異なる形で動作します。 システムからの値、あるいは、コンフィギュレーションファイルで設定された値など、いかなる値でも上書きされ、 コマンドラインからの値が有効になります。 コンフィギュレーションファイル 「wrapper.conf」 内部のデフォルト環境変数を定義しつつも、 さらにコマンドラインからその値を書き換えることが可能です。

Windows でのコマンドライン:(注意:プロパティ値にスペースが含まれている)
wrapper.exe -c ..\conf\wrapper.conf "set.EXTERN_APP=C:\Program Files\ExternAppHome"
UNIX でのコマンドライン:
wrapper ../conf/wrapper.conf set.EXTERN_APP=/usr/lib/externapphome

注意

コマンドラインから利用する際には、 プロパティ値にスペース(空白)を含んでいる場合、プロパティセット(プロパティ名とその値)の全体の値を、 開始と終わりに引用符(" ")で囲ってください。

注意

循環参照雅設定されている変数は、コンフィギュレーションが再ロードされる都度(最低でも起動時に必要で、JVM 再起動の時に任意)に長くなる既知の問題があります。

典型的な例は「PATH」環境変数にパスを追加するときです:

set.PATH=my_path%WRAPPER_PATH_SEPARATOR%%PATH%.
上記の定義では、コンフィギュレーションが再ロードされるたびに「my_path」が「PATH」に追加されます。

現在、この問題を解決するための解決策に取り組んでいますが、 しかし、当面の間は回避策として、一度しか設定されない一時変数を使用できます。

set.default.MYPATH=my_path%WRAPPER_PATH_SEPARATOR%%PATH%.
set.PATH=%MYPATH%

デフォルト環境変数の定義

Wrapper 起動時に、次の環境変数を設定します。 これらの変数は、コンフィギュレーションファイル 「wrapper.conf」 内部で使われたり、JVM の環境へアクセス、あるいは、そのチャイルド(子)プロセスへアクセスしたりして使われます。

  • [WRAPPER_ARCH] 変数は、 現在動作中の Wrapper がビルドされた構造名に設定されます。 (バージョン 3.3.0 から)

  • [WRAPPER_BASE_NAME] 変数は、 拡張子を除いたバイナリーファイル名に設定されます。 もし、ファイル名に OS、アーキテクチャー、ビット数が含まれている場合、そちらも環境変数空除かれます。 (バージョン 3.5.41 から)

  • [WRAPPER_BIN_DIR] 変数は、 スタートアップ時の Wrapper バイナリの配置場所に設定されます。 たとえカレント(現在の)作業ディレクトリーが変更されていたとしても、それとは関係なく、 その場所への相対パスを定義するために使われます。 (バージョン 3.3.0 から)

  • [WRAPPER_BITS] 変数は、 現在動作中の Wrapper がビルドされた、32 ビットや 64 ビットの深さに設定されます。 (バージョン 3.3.0 から)

  • [WRAPPER_EDITION] 変数は、 現在動作中の Wrapper のエディションに設定されます。 有効な値は、「Community」、「Standard」と「Professional」です。 (バージョン 3.5.36 から)

  • [WRAPPER_FILE_SEPARATOR] 変数は、 ファイルセパレーターとして、Windows 上で「\」、 Linux/UNIX プラットフォーム上で「/」に設定されます。 その変数は、追加の環境変数やプロパティのために、 プラットフォームに依存しない独立型の値を設定するために利用されます。 (バージョン 3.1.0 から)

    一般的に、安全をみて、 Java 内部で使われるパスのファイルセパレーターとして、 常に「/(スラッシュ)」を使うことをお薦めします。 Java では、「/」 を使えば、全てのプラットフォーム上で正しく動くように設計されています。

  • [WRAPPER_HOSTNAME] 変数と [WRAPPER_HOST_NAME] 変数は、 Wrapper が現在動作しているマシンの解決した名前に設定されます。 (WRAPPER_HOST_NAMEバージョン 3.3.2 からで、 WRAPPER_HOSTNAMEバージョン 3.3.6 から)

  • [WRAPPER_INIT_DIR] 変数は、 Wrapper プロセスを起動するプロセスの作業ディレクトリーに設定されます。 Wrapper は常に最初に、コンフィギュレーションファイルの読み込み中、 作業ディレクトリーを Wrapper バイナリがある場所に強制設定します。 (参照: WRAPPER_BIN_DIR 変数) その後、もしユーザーが他の作業ディレクトリーを設定していた場合、 [wrapper.working.dir] プロパティで指定された場所へ変更されます。 これは、どこから Wrapper が起動されたかに関わらず、 与えられたコンフィギュレーションを100%信頼して、 確実に Wrapper が動作することを実現させるために必要です。 一部のアプリケーションでは、Wrapper を起動する時、ユーザーがどこに居るのか知る必要があります。 そのようなケースで、この変数が利用されます。 (バージョン 3.5.6 から)

    コンフィギュレーションファイルの設定例:
    wrapper.java.additional.1=-myinit.working.dir="%WRAPPER_INIT_DIR%"
    wrapper.java.additional.1.stripquotes=TRUE
    
  • [WRAPPER_JAVA_HOME] 変数は、 システムレジストリを使って Java コマンドが配置される時、Windows プラットフォーム上で、設定されます。 その他のケースでは、[JAVA_HOME]変数を設定することをお薦めします。 (バージョン 3.3.0 から)

  • [WRAPPER_JAVA_VENDOR] 変数は、 コンフィギュレーションがロード(読込み)され、JVM に「java -version」コマンドの出力が解釈された後に設定されます。 この値は、現在使用されている Java ベンダーを表す文字列です。 (バージョン 3.5.37 から)

    この変数は、Java バージョンが解析された後にロードされる任意のプロパティ値で使用できます。 それは、イベントプロパティwrapper.java.additional_filewrapper.app.parameter_file を含みます。

  • [WRAPPER_JAVA_VERSION] 変数は、 コンフィギュレーションがロード(読込み)され、JVM に「java -version」コマンドの出力が解釈された後に設定されます。 この値は、現在使用されている Java バージョンを表す文字列です。 (バージョン 3.5.36 から)

    この変数は、Java バージョンが解析された後にロードされる任意のプロパティ値で使用できます。 それは、イベントプロパティwrapper.java.additional_filewrapper.app.parameter_file を含みます。

  • [WRAPPER_JAVA_VERSION_MAJOR] 、 [WRAPPER_JAVA_VERSION_MINOR] と [WRAPPER_JAVA_VERSION_REVISION] 変数は、 コンフィギュレーションがロード(読込み)され、JVM に「java -version」コマンドの出力が解釈された後に設定されます。 現在使用されている Java バージョンの「major」、「minor」と「revision」番号を含みます。 (バージョン 3.5.36 から)

    この変数は、Java バージョンが解析された後にロードされる任意のプロパティ値で利用できます。 それは、イベントプロパティwrapper.java.additional_filewrapper.app.parameter_file を含みます。

  • [WRAPPER_LANG] 変数は、 Wrapper で利用する言語を表す小文字を 2 文字のコードに設定されます。 コミュニティー版では、その値は常に「en」です。 その言語用に、値をローカライズした コンフィギュレーションファイル の一部として含めることができます。 (バージョン 3.5.5 から)

    次の例では、Windows サービス表示名や説明をローカライズする方法を示しています。 最初に、確実に英語が常にロード(読み込み)される(或いは最初に英語プロパティが定義される) ことに注目してください。 これは、英語の値がデフォルトとして存在することを明確にするためです。 その後、Wrapper は、その英語の値をローカライズされた インクルードファイル(カスケード形式)の値で上書きします。

    例(wrapper.conf):
    #encoding=UTF-8
    #include ../conf/wrapper-en.conf
    #include ../conf/wrapper-%WRAPPER_LANG%.conf
    ...
    wrapper.ntservice.name=myapp
    ...
    
    例(wrapper-en.conf):
    #encoding=UTF-8
    wrapper.ntservice.displayname=My App Server
    wrapper.ntservice.description=Application Server that does cool stuff.
    
    例(wrapper-de.conf):
    #encoding=UTF-8
    wrapper.ntservice.displayname=My App Server
    wrapper.ntservice.description=Application Server that does cool stuff.
    
  • [WRAPPER_OS] 変数は、 現在動作している Wrapper がビルドされた OS 名に設定されます。 (バージョン 3.3.0 から)

    コンフィギュレーションファイルの設定例:
    wrapper.java.library.path.1=../lib
    wrapper.java.library.path.2=../lib/native/%WRAPPER_OS%-%WRAPPER_ARCH%-%WRAPPER_BITS%
    

    上記の例では、以下のように解決されます:

    Windows の場合:
    wrapper.java.library.path.1=../lib
    wrapper.java.library.path.2=../lib/native/windows-x86-32
    
    Linux の場合:
    wrapper.java.library.path.1=../lib
    wrapper.java.library.path.2=../lib/native/linux-x86-32
    
    Solaris の場合:
    wrapper.java.library.path.1=../lib
    wrapper.java.library.path.2=../lib/native/solaris-sparc-32
    
  • [WRAPPER_PATH_SEPARATOR] 変数は、 Windows 上で「;」、 Linux/UNIX プラットフォーム上で、「:」に設定されます。 この変数は、プラットフォームに依存しない独立型のパスをビルドするために使われます。 (バージョン 3.1.0 から)

    コンフィギュレーションファイルの設定例:
    set.PATH=..%WRAPPER_FILE_SEPARATOR%lib%WRAPPER_PATH_SEPARATOR%%PATH%
    

    上記の例では、以下のように解決されます:

    Windows の場合:
    set.PATH=..\lib;%PATH%
    
    UNIX の場合:
    set.PATH=../lib:%PATH%
    
  • [WRAPPER_PID] 変数は、 起動時に、Wrapper プロセスの PID に設定されます。 同じコンフィギュレーションファイルを使って複数のアプリケーションを起動するときに、 固有のファイル名を取得していることを確認するために、 PID ファイルログファイルのようなファイル名の中で使われます。 (バージョン 3.3.7 から)

    コンフィギュレーションファイルの設定例:
    wrapper.logfile=../logs/wrapper-%WRAPPER_PID%.log
    
  • [WRAPPER_RUN_MODE] 変数は、 コンソールとして作動するときに「console」に設定され、Windows サービスや Unix デーモンとして作動した場合は「service」に設定されます。 (バージョン 3.5.41 から)

  • [WRAPPER_VERSION] 変数は、 現在作動されている Wrapper のバージョンに設定されます。 (バージョン 3.5.36 から)

  • [WRAPPER_WORKING_DIR] 変数は、 スタートアップ時に Wrapper バイナリの配置場所に設定されますが、 チャイルド(子)プロセスによって参照されるとき、 Wrapper のカレント作業ディレクトリーを反映して変更されます。 (バージョン 3.3.0 から)

    Wrapper の作業ディレクトリーは、 [wrapper.working.dir]プロパティを使って変更することができます。 その使い方は少しヤヤコシイので必ず説明を読んでください。

    しかしながら、このプロパティが設定されるこの方法ゆえに、次の点に注目してください。 Wrapper コンフィギュレーションファイル内で参照されるとき、 それは常に[WRAPPER_BIN_DIR]変数と同等です。 この変数は、環境内部で正確に設定されますが、どのチャイルド(子)プロセスも、 [wrapper.working.dir] プロパティで設定されたディレクトリーを参照します。

擬似環境変数の定義

上記環境変数に加え、次の変数は Wrapper に作成されますが、環境に格納されません。

「WRAPPER_RAND_NNNNNN」と「WRAPPER_TIME_YYYYMMDDHHIISS」変数は、 コンフィギュレーションファイル内に数回参照することが出来て、各参照に異なる値を生成することが出来ます。 そのため、環境に格納されません。 「"set.<X>"」シンタックスを利用することで1つの参照に対して生成された値を 自分の環境変数に格納することはできますが、環境変数の値が変更される度、基礎となるシステム関数を呼び出すと、 わずかなメモリリークが発生します。 これらの変数の値は再生成され、毎回変更されるため、コンフィギュレーションファイルを複数回再ロードできる場合は、 これを考慮する必要があります。

カスタム環境変数に格納されるランダムな値の例:
set.RAND_NNNNNN=%WRAPPER_RAND_NNNNNN%

イベントハンドラ変数の定義

上記の環境変数に加え、イベントプロパティの中で以下の変数も参照され、イベントが発生するときに使用されます。 これらの変数は、Wrapper コンフィギュレーションで使用され、環境に格納されませんので注意してください。

  • [WRAPPER_NAME] 変数は、 [wrapper.name]プロパティの値に設定されます。 (バージョン 3.3.0 から)

  • [WRAPPER_DISPLAYNAME] 変数は、 [wrapper.displayname]プロパティの値に設定されます。 (バージョン 3.3.0 から)

  • [WRAPPER_DESCRIPTION] 変数は、 [wrapper.description]プロパティの値に設定されます。 (バージョン 3.3.0 から)

  • [WRAPPER_EVENT_JVM_ID] 変数は、 JVM が再起動した回数を示し、1で始まる1つのインテージャー値(整数値)に設定されます。 jvm_*]イベントのためだけに設定されます。 (バージョン 3.3.0 から)

  • [WRAPPER_EVENT_JVM_PID] 変数は、 JVM プロセスの PID を含む1つのインテージャー値(整数値)に設定されます。 [jvm_prelaunch]イベント以外の jvm_*]イベントのためだけに設定されます。 (バージョン 3.3.0 から)

  • [WRAPPER_EVENT_NAME] 変数には、 発生したイベント名が設定されます。 (バージョン 3.3.0 から)

  • [WRAPPER_EVENT_RAND_NNNNNN] 変数には、 イベントが発生する度にランダムな数字が設定されます。 (バージョン 3.5.25 から)

    設定例:
    wrapper.event.default.message=Event: %WRAPPER_EVENT_NAME% %WRAPPER_RAND_NNNNNN% %WRAPPER_EVENT_RAND_NNNNNN%
    

    上記の例では、2つのランダムな数字が生成されます。 最初の数字[WRAPPER_RAND_NNNNNN]は、Wrapper コンフィギュレーションファイルがロードされる都度に設定されます。 2つ目[WRAPPER_EVENT_RAND_NNNNNN]は、イベント毎に変更されます。 [WRAPPER_EVENT_RAND_NNNNNN] の値は動的に解決されるため、再利用することが出来ません。

    さらに、追加的な形式として、1桁から6桁のランダムな数字で存在します: [WRAPPER_EVENT_RAND_N]、 [WRAPPER_EVENT_RAND_NN]、 [WRAPPER_EVENT_RAND_NNN]、 [WRAPPER_EVENT_RAND_NNNN]、 [WRAPPER_EVENT_RAND_NNNNN]、 WRAPPER_EVENT_RAND_NNNNNN

  • [WRAPPER_EVENT_TIME_YYYYMMDDHHIISS] 変数には、 イベントが発生する度にタイムスタンプが設定されます。 (バージョン 3.5.25 から)

    設定例:
    wrapper.event.default.message=Event: %WRAPPER_EVENT_NAME% %WRAPPER_TIME_YYYYMMDDHHIISS% %WRAPPER_EVENT_TIME_YYYYMMDDHHIISS%
    

    上記の例では、2つのタイムスタンプが参照されます。 [WRAPPER_TIME_YYYYMMDDHHIISS]は、Wrapper コンフィギュレーションファイルがロードされる都度に設定され、 [WRAPPER_EVENT_TIME_YYYYMMDDHHIISS]は、イベント毎に変更されます。 同じ時間がイベントの実行中に使用されますので、複数の時間参照を使用できます。

    さらに、追加的な形式として、参照されるもの: [WRAPPER_EVENT_TIME_YYYYMMDD_HHIISS]、 [WRAPPER_EVENT_TIME_YYYYMMDDHHII]、 [WRAPPER_EVENT_TIME_YYYYMMDDHH]、 [WRAPPER_EVENT_TIME_YYYYMMDD

  • [WRAPPER_EVENT_WRAPPER_PID] 変数は、 Wrapper プロセスの PID を含む1つのインテージャー値(整数値)に設定されます。 (この環境変数は、[WRAPPER_PID]環境変数のエイリアスであり、 互換性の都合上の理由のためだけに利用されています) (バージョン 3.3.0 から)