概要：コンフィギュレーションファイル ディレクティブ

Java Service Wrapper がコンフィギュレーションファイルを解釈する際に、ほとんどの場合、 「#」文字に続く全てのテキスト文字は、コメントとして無視されます。 しかしながら、そのルールに少し例外があります。

Wrapper は従来からの方式で、コンフィギュレーションファイルをロード（読み込み）して処理する、 特別なディレクティブを定義するＣ言語パターンを使用してきました。

コンフィギュレーションファイルのエンコード指定

Wrapper ver. 3.5.0 から、 個別のコンフィギュレーションファイルのエンコードの指定が可能になりました。 最もポータブルなエンコードは、UTF-8 ですが、 他のエンコードは、一部のプラットフォーム上でサポートされています。

エンコードディレクティブは、コンフィギュレーションファイルの 一行目で指定しなければなりません。 Wrapper では、ディレクティブが不足しているファイルがあれば、その警告をログに出力します。 インクルードファイル（カスケード形式）に異なるエンコードを指定することが可能です。

UTF-8 設定例： 
#encoding=UTF-8

wrapper.debug=FALSE
...

コンフィギュレーションファイルのインクルード ファイル（カスケード形式）

コンフィギュレーションを分割して複数のコンフィギュレーションファイルにすることが可能であり、 メインのコンフィギュレーションファイルにインクルードファイル（カスケード形式）として含めることができます。 詳しくは『コンフィギュレーションファイルのカスケード（インクルード ファイル）』ページをご覧ください。

設定例：（インクルードファイルの指定） 
#include ../conf/wrapper-settings.conf

Wrapper は、何かの理由で参照できない／存在しないインクルードファイル （カスケード形式）があった場合でも、警告は出さずに意図的に静かにスキップします。 これは、むしろ、プラットフォーム別に特定のコンフィギュレーションを用意したり、 既存プロパティ値の任意的な上書きを可能にできるので、とてもパワフルな機能です。

しかし、一部のケースでは、アプリケーションの正しいオペレーションの一部として、 インクルードファイル（カスケード形式）を必須にしたい場合もあります。 Wrapper ver. 3.5.5から、必須のインクルードファイル（カスケード形式）を指定することが可能で、 そのファイルが不足していた場合にエラーを表示して、Wrapper の起動を阻止することができます。

設定例：（インクルードファイルの必須指定） 
#include.required ../conf/wrapper-settings.conf

インクルードファイル（カスケード形式）のデバッグ

Wrapper ver. 3.3.0 から、何が含まれている／含まれていないかを正確に探して、「#include」ディレクティブの動作方法をデバッグすることが可能になりました。 詳しくは『インクルードファイル（カスケード形式）のデバッグメッセージ有効化』ページをご覧ください。

設定例： 
#include.debug

プロパティのデバッグ

Wrapper ver. 3.5.4 から、 他の宣言によってプロパティが上書きされたとき、または値が固定されているためにプロパティを 設定できないときに、スタートアップ時に Wrapper がメッセージを出力するように設定出来ます。

Wrapper ver. 3.5.27 では、その機能を改善します。 今では、そのメッセージのログレベルをコントロールでき、Wrapper が出力後に終了するかしないかを設定できます。 また、コンフィギュレーションファイルのセクションごとに異なる設定を適用することもできます。 そのため、一部で制限レベルを高く、或いは低くすることができます。これは、次の２つの新しいディレクティブを使用して達成できます。

プロパティの性質によって、Wrapper は異なるメッセージを出力します。 これらのメッセージは、 下記に説明されています。

注意

オプションのカスケード形式コンフィギュレーションファイル（インクルードファイルまたはその他の方法を使用してプロパティ値を上書きするのが一般的であるため、これらのメッセージはデフォルトでは『debug』モードでのみ記録されます。

警告

［wrapper.name］と［wrapper.displayname］プロパティは UNIX シェルスクリプトで 定義されているため、このスクリプトを使用して Wrapper を起動し、上記のディレクティブを使用してプロパティをデバッグすると、 これらの変数もコンフィギュレーションファイルでデフォルトで定義されているため、警告メッセージが表示されることがあります。

コンフィギュレーションファイルの冗長プロパティーを削除する、或いはスクリプトファイルの 「#APP_NAME_PASS_TO_WRAPPER=false」行のコメント記号（＃）を外すことで これらのメッセージの表示を防ぐことができます。

２番目のオプションは、スクリプトがこれらのパラメータを Wrapper に渡さないようにします。 ［APP_NAME］や［APP_LONG_NAME］プロパティは、スクリプトの正常な動作に必要ですので 決して無効にしないように注意してください。

表示されるメッセージ

プロパティに特定の値がある理由を理解するために、その値が変更されたときや、逆に 値を上書きしようとして無視された時に視覚化すると便利です。

次のメッセージが表示されることがあります。

重複したプロパティ：

Wrapper は、特定のプロパティの一番最後に定義されたインスタンスを使用するように設定されています。 これは、デフォルト値を設定して、システムに固有の値を含むオプションのインクルードファイルを 参照するのでとても強力です。

プロパティ再定義の例： 
STATUS | wrapper  | 「foo.bar」プロパティは、コンフィギュレーションファイルの行番 #8 で再定義されました: /home/wrapper/conf/wrapper.conf
STATUS | wrapper  |   古い値 foo.bar=123
STATUS | wrapper  |   新しい値 foo.bar=XYZ

コマンドラインのプロパティ：

Wrapper コマンドラインで指定されたプロパティ値は「最終値」であり、 つまり、コンフィギュレーションファイルの値で変更したり上書きすることはできません。 実際のコンフィギュレーションファイルを変更することなく、ユーザーがテスト値で Wrapper を動作させることができ、とても便利です。

最終的プロパティ再定義の例： 
STATUS | wrapper  | 「foo.bar」プロパティは Wrapper コマンドライン上で定義され、上書きできません。
STATUS | wrapper  |   コンフィギュレーションファイルの行番 #8 での再定義を無視: /home/wrapper/conf/wrapper.conf
STATUS | wrapper  |   修正された値 foo.bar=123
STATUS | wrapper  |   無視された値 foo.bar=XYZ

内部環境変数：

Wrapper は、いくつかの内部環境変数を設定します。 それらは、最終的プロパティで設定されます。 もし、ユーザーコンフィギュレーションファイルでどれか環境変数の設定を試みても、Wrapper はそれを無視して、Wrapper によって設定される値を持続します。

最終的プロパティ再定義の例： 
STATUS | wrapper  | 「set.WRAPPER_ARCH」プロパティは Wrapper により内部的に定義され、上書きできません。
STATUS | wrapper  |   コンフィギュレーションファイルの行番 #10 での再定義を無視: /home/wrapper/conf/wrapper.conf
STATUS | wrapper  |   修正された値 set.WRAPPER_ARCH=x86
STATUS | wrapper  |   無視された値 set.WRAPPER_ARCH=special

#properties.on_overwrite.loglevel
対応バージョン :3.5.27
対応エディション :プロフェッショナル版スタンダード版コミュニティー版
対応プラットフォーム :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

このディレクティブは、ログ化されるメッセージのログレベルを設定します。

有効な値：

  • 「AUTO」： ログレベルを自動的に解決するためのデフォルト値です（下記を参照）。

  • 「NOTICE」：「NOTICE」ログレベルでログ化します。

  • 「ADVICE」：「ADVICE」ログレベルでログ化します。

  • 「FATAL」：「FATAL」ログレベルでログ化します。

  • 「ERROR」：「ERROR」ログレベルでログ化します。

  • 「WARN」：「WARN」ログレベルでログ化します。

  • 「STATUS」：「STATUS」ログレベルでログ化します。

  • 「INFO」：「INFO」ログレベルでログ化します。

  • 「DEBUG」：「DEBUG」ログレベルでログ化します。

デフォルト値は「AUTO」で、同じコンフィギュレーションファイル内、 または以前の定義のファイルより低いインクルード深層にあるファイル内で プロパティが上書きされるときに、「WARN」に解決されます。 また、カスタマイズ中に埋め込まれた最終的（final）プロパティが 上書きされるときにも、「WARN」に解決されます。それ以外の場合は常に「DEBUG」に解決されます。

注意

Wrapper ver. 3.5.36 までは、このディレクティブのデフォルト値は「DEBUG」でした。

設定例（上書きされたプロパティを「WARN」レベルでログ化します）： 
#properties.on_overwrite.loglevel=WARN

注意

Wrapper ver. 3.5.27より、「#properties.debug」ディレクティブの使用を非推奨にし、 代わりにデバッグプロパティの細かい制御を提供する新しいディレクティブを使用します。 下位互換性のため、「#properties.debug」は、「#properties.on_overwrite.loglevel=STATUS」と同じ結果を出します。

#properties.on_overwrite.exit
対応バージョン :3.5.27
対応エディション :プロフェッショナル版スタンダード版コミュニティー版
対応プラットフォーム :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

このディレクティブは、一つでもプロパティが上書きされたら Wrapper が終了するかどうかを指定します。

有効な値：

  • 「TRUE」：このディレクティブの後のプロパティが上書きされると、Wrapper を終了するように設定します。

  • 「FALSE」：このディレクティブの後のプロパティが上書きされても、Wrapper を終了しないるように設定します。

デフォルト値は「FALSE」です。

設定例（プロパティが上書きされると終了します）： 
#properties.on_overwrite.exit=TRUE

使用方法

各ディレクティブは、コンフィギュレーションファイル内でディレクティブが挿入された行からファイルの終わりまで、 または同じ名前の次のディレクティブがが検出されるまで有効です。新しいディレクティブが検出されると、 その値はコンフィギュレーションファイル内の次のセクションで有効になります。

「#properties.on_overwrite.exit」を「TRUE」に設定すると、「#properties.on_overwrite.loglevel」の値は自動的に「FATAL」に上げられます（FATAL 以下に設定している場合）。 これは、「#properties.on_overwrite.exit」を｢FALSE」に設定するまで、そのまま留まります。

設定例： 
wrapper.name=@app.name@
wrapper.lang.folder=../lang
...

#properties.on_overwrite.loglevel=STATUS
wrapper.lang.folder=../../lang
...

#properties.on_overwrite.loglevel=INFO
wrapper.name=newAppName
...

#properties.on_overwrite.exit=TRUE
wrapper.app.parameter.3=start
...

wrapper.app.parameter.3=start_app
...

#properties.on_overwrite.exit=FALSE
...

上記設定では、［wrapper.lang.folder］は「STATUS」レベルでログ化され、［wrapper.name］は「INFO」レベルで、 ［wrapper.app.parameter.3］は「FATAL」レベルでログ化され、Wrapper を終了させます。 『#properties.on_overwrite.exit=FALSE』以降のプロパティは Wrapper を終了せず、 「INFO」レベルでログ化されます（以前設定した通り）。

注意

Wrapper ver. 3.5.27 より、 コマンドラインが重複しているプロパティを含む場合、或いは内部環境変数の設定を試みるときに Wrapper がメッセージを記録します。

これらのメッセージが記録されるログレベルや、記録後に Wrapper は終了するかを制限するために「#properties.on_overwrite.loglevel」と「#properties.on_overwrite.exit」を使うこともできます。コンフィギュレーションファイルに複数のディレクティブが設定されている場合、各タイプの最後のディレクティブが適用されます。

変数の展開の切り替え
対応バージョン :3.5.55
対応エディション :プロフェッショナル版スタンダード版コミュニティー版
対応プラットフォーム :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

すべてのコンフィギュレーションプロパティ値は、次の構文を使用して変数を参照できます：%MYVAR%。 変数の定義方法と事前定義された変数のリストの詳細については、環境変数のページを参照してください。

Wrapper ver. 3.5.55 以降では、コンフィギュレーションファイルのセクションの変数展開 (つまり、上記の構文表記を変数の値に置き換えること) を有効または無効にすることができます。

デフォルトでは (このディレクティブが使用されていない場合)、変数の展開が有効になります。 コンフィギュレーションファイルの任意の場所に「#variables.expand=FALSE」を追加することで無効にできます。 後続の行で参照されるプロパティは変数を展開しません。 「#variables.expand=TRUE」を使用すると、特定の行から始まる変数展開を再度有効にすることができます。

設定例： 
set.MYVAR=some_value

#variables.expand=FALSE

# %MYVAR% は展開されません。
wrapper.app.parameter.1=%MYVAR% 

#variables.expand=TRUE

# %MYVAR% は 'some_value' に展開されます。
wrapper.app.parameter.2=%MYVAR%

注意

変数展開の無効化は、現在のコンフィギュレーションファイルにのみ適用され、インクルードファイルには適用されません。 #variables.expand が「FALSE 」に設定された後にファイルがインクルードされる場合、ファイル自体も #variables.expand=FALSE を指定しない限り、インクルードファイルで参照される変数は展開されます。

なぜ便利なのでしょうか?

場合によっては、プロパティ値に「%」文字を使用する必要がある場合があります。 この文字が同じ値内で 2 回参照されると、変数を参照するつもりがなかった場合でも、変数の区切り文字として解釈されます。

設定例：（次の値を指定すると、「20with」 環境変数が参照されましたが、定義されていません」という警告が生成されます。） 
wrapper.app.parameter.1=http://url%20with%20spaces

この問題を回避するには、値が 1 つの「%」文字である特別な変数「%WRAPPER_PERCENTAGE%」を使用することが考えられます。

設定例：（警告は生成されずに「http://url%20with%20spaces」に展開されます) 
wrapper.app.parameter.1=http://url%WRAPPER_PERCENTAGE%20with%WRAPPER_PERCENTAGE%20spaces

ただし、特に「%」が何度も使用されている場合、値が読みにくくなる可能性があります。

#variables.expand は、コンフィギュレーションの特定の部分が変数を参照しておらず、変数区切り文字として解釈されずに「%」 文字を使用する必要があることがわかっている場合に、変数展開を完全に無効にする代替手段を提供します。

参照： ログレベル
  • [ wrapper.console.loglevel ] (1.0.0)

    コンソールへ出力されるメッセージをログレベルに応じてフィルタリングします。

  • [ wrapper.logdialog.loglevel ] (3.3.1)

    ログダイアログのメッセージをログレベルに応じてフィルタリングします。

  • [ wrapper.logfile.loglevel ] (2.2.5)

    ログファイルへ出力されるメッセージをログレベルに応じてフィルタリングします。

  • [ wrapper.syslog.loglevel ] (2.2.5)

    「syslog」（または Windows のイベントログ）へ送信されるメッセージをログレベルに応じてフィルタリングします。