N1 Grid Service Provisioning System 5.0 XML スキーマリファレンスガイド

第 2 章コンポーネントと単純プランにより使用される共有スキーマ

この章では、単純プランとコンポーネントの両方により使用可能な 3 つの共有エンティティについて説明します。

特に断りのない限り、この章で説明する属性は、コンポーネントスコープの置換変数を参照できません。

共有ステップ

この節では、コンポーネントまたは単純プランのいずれかで使用可能なステップを説明します。

`<call>` ステップ

ターゲットホストにインストールされているコンポーネントに関連付けられた制御ブロックを実行するには、<call> ステップを使用します。

<call> ステップには次の子要素があります。

<argList> – オプション要素で、制御ブロックに渡す引数の一覧。この要素を指定する場合、この要素は 1 回しか出現できません。
インストール済みコンポーネントターゲッター – 実行する制御ブロックが含まれるコンポーネントを特定するオプション要素。この要素は <call> ステップがコンポーネントに出現する場合はオプションになりますが、ステップがプランに出現する場合はオプションではありません。この要素を省略すると、<thisComponent> が使用されます。この要素を指定する場合、この要素は 1 回しか出現できません。詳細は、「インストール済みコンポーネントターゲッター」を参照してください。

`<call>` ステップの属性

<call> 要素には、blockName 型の 1 つの必須属性 entityName があり、これはインストール済みコンポーネントに対して実行する制御ブロックの名前です。

`<argList>` 要素

<argList> 要素は、<call>、<install>、<uninstall>、<execSubplan>、および <addSnapshot> ステップの子です。この要素は、呼び出されるサービスに引数として渡される一連の変数を指定します。

呼び出されるサービスの方は、待ち受ける変数を <paramList> 要素を使用して宣言します。<argList> 内の変数と呼び出される <paramList> 内の変数は同じである必要はありません。しかし、呼び出される <paramList> 内の変数のうちデフォルト値を持たないものについては、<argList> 内に同じ名前の変数が存在しなければなりません。この条件が満たされない場合、プラン実行時にプリフライトエラーが発生します。呼び出される <paramList> 内の変数のうち <argList> 内に対応する変数が存在するものは、呼び出されるサービスの実行時に <argList> 内の対応する変数の値をその値として取得します。

<argList> 内の変数のうち呼び出される <paramList> 内の変数に対応しないものは、単純に無視されます。よって、下位互換性を維持しながら、追加されたパラメータによりサービスを再定義できます。そのため、1 つのプランで新旧両方のサービスバージョンを呼び出すことができます。

<argList> 要素の引数は属性として表現されます。引数の順番はあまり重要ではありません。たとえば、次の <argList> は 2 つの引数、「password」と「path」を宣言しています。

<argList password=":[password]" path="/tmp"/>

`<argList>` 要素属性

<argList> 要素には、属性を少なくとも 1 つは指定する必要があります。各属性は、呼び出されるサービスに渡される名前付き変数として扱われます。各属性の名前は置換変数参照のない識別子でなければならず、呼び出されるサービス内のパラメータの名前に対応する必要があります。各属性の値は任意の文字列であり、包含するスコープ内の変数の参照を含むことができます (<argList> 内のほかの引数は含むことができない)。

`<checkDependency>` ステップ

<checkDependency> ステップは、特定のコンポーネントがターゲットホスト上にインストール済みであることを検証するために使用できます。適切なコンポーネントがインストールされていない場合、ステップは失敗し、実行が停止します。

この処理では、包含されているコンポーネントターゲッターによって依存性がチェックされます。このターゲッターが正常にコンポーネントを解決処理すると、依存性が満たされます。正常に解決処理されない場合、依存性は満たされません。

<checkDependency> ステップには、1 つの必須子要素があり、これはインストール済みのコンポーネントターゲッターで、依存性をチェックするコンポーネントを特定します。詳細は、「インストール済みコンポーネントターゲッター」を参照してください。

`<execJava>` ステップ

このステップは、ターゲットホスト上で Java ^TM Executor インスタンスを実行します。Executor インスタンスが例外を送出する場合、ステップは失敗し、実行が停止します。

<execJava> ステップには、1 つのオプション子要素である <argList> があり、これは Executor インスタンスに渡す引数の一覧です。この要素を指定する場合、この要素は 1 回しか出現できません。

`<execJava>` ステップの属性

<execJava> 要素には次の属性があります。

className – 必須属性で、(Plan Executor で指定されているとおりに) ExecutorFactory インタフェースを実装する、public no-arg コンストラクタを持つ public クラスのフルネーム。この属性は、単純置換変数を参照できます。
classPath – オプション属性で、className 属性で指定されたクラスを含むクラスパス。この属性を指定しないと、Remote Agent のシステムクラスパスが使用されます。クラスパスの形式は、エージェント上の Java Archive (JAR) ファイルの絶対パスをセミコロンで区切ったリストです。この属性は、単純置換変数を参照できます。
timeout – positiveInteger 型のオプション属性で、コマンドの完了を待機する時間を秒数で指定し、この時間を経過するとタイムアウトになります。この属性を指定しないと、プランの <execNative> タイムアウト期間が適用されます。この値は 0 より大きくする必要があります。

<execJava> ステップがコンポーネント内に含まれる場合、通常このステップはそのコンポーネントによって配備された 1 つ以上のリソースに含まれるクラスを呼び出します。ステップがプラン内に含まれる場合、呼び出されるクラスはエージェント自体のシステムクラスとして、あるいは既存コンポーネントによって配備されたリソースとして、エージェント上にすでに存在します。

`<execNative>` ステップ

<execNative> ステップは、ターゲットホストでオペレーティングシステムに対してネイティブコマンドを実行します。コマンドが予期しなかった結果を生成する場合、ステップは失敗し、実行が停止します。

<execNative< ステップには次の子要素があります。

<env> – オプション要素で、子プロセスの環境変数を指定します。各環境変数に対しては、1 つの <env> 要素を指定します。
<background> – オプション要素で、コマンドをバックグラウンドプロセスとして実行することを指定します。この要素を指定する場合、この要素は 1 回しか出現できません。<background> 要素を指定する場合は、<outputFile> 要素と <errorFile> 要素も指定する必要があります。
<outputFile> – オプション要素で、コマンドの標準出力を格納するファイルの名前。この要素を指定する場合、この要素は 1 回しか出現できません。この要素は、<background> 要素が指定してある場合は必須要素になります。
<errorFile> – オプション要素で、コマンドの標準エラー出力を格納するファイルの名前。この要素を指定する場合、この要素は 1 回しか出現できません。この要素は、<background> 要素が指定してある場合は必須要素になります。
<inputText> – オプション要素で、コマンドの標準入力として使用するテキスト。この要素を指定する場合、この要素は 1 回しか出現できません。<inputFile> 要素が指定されていると、この要素は指定できません。
<inputFile> – オプション要素で、コマンドの標準入力として使用するファイル名。この要素を指定する場合、この要素は 1 回しか出現できません。<inputText> 要素が指定されていると、この要素は指定できません。
<exec> – 必須要素で、実行する実行可能ファイル名を指定します。<shell> 要素が指定されていると、この要素は指定できません。
<shell> – 必須要素で、実行するシェルコマンドを指定します。この要素は 1 回しか出現できません。<exec> 要素が指定されていると、この要素は指定できません。
<successCriteria> – オプション要素で、このステップが成功したか失敗したかを判断するために使用される基準。この要素を指定する場合、この要素は 1 回しか出現できません。

`<execNative>` ステップの属性

<execNative> ステップには次の属性があります。

userToRunAs – オプション属性で、このコマンドを実行するためのユーザーの名前。この属性を指定しないと、コマンドは構成ファイル内の defaultUserToRunAs の値として実行されます。値として、文字列によるユーザー名または数値によるユーザー ID を指定できます。この値は、空でない文字列にする必要があります。この属性は、単純置換変数を参照できます。
dir – オプション属性で、コマンドの作業ディレクトリの絶対パス。この属性を指定しないと、値のデフォルトはエージェント固有の構成可能ディレクトリになります。この値は、空でない文字列にする必要があります。この属性は、単純置換変数を参照できます。
timeout – positiveInteger 型のオプション属性で、コマンドの完了を待機する時間を秒数で指定します。この時間を経過するとタイムアウトとなります。この属性を指定しないと、プランの <execNative> タイムアウト期間が適用されます。この値は 0 より大きくする必要があります。

`<env>` 要素

<execNative> 要素は、コマンドの環境変数を指定する目的で、必要に応じて <env> 要素を含むことができます。<env> を使用すると、コマンド環境の新しい変数を提供することも、既存の変数を無効にすることもできます。

コマンドの環境変数セットは、Remote Agent の環境変数セットと、<env> 要素を使用して提供される変数を合わせたものです。

`<env>` 要素属性

<env> 要素には次の属性があります。これらの属性は、単純置換変数を参照できます。

name – 必須属性で、環境変数の名前。この値は、空でない文字列にする必要があります。
value – 必須属性で、環境変数の値。この値には、Remote Agent の環境変数の値を参照するように、 ${var-name } 文字列を含めることができます。<env> 要素により無効にされた変数を var-name が参照する場合、その置換された値は Remote Agent の環境内で定義されたものであり、無効にされた値ではありません。値に ${ という文字列を表示させる必要がある場合は、 ${{ を使用してこの文字列をエスケープします。${{ のインスタンスはすべて ${ に置換されます。

`<background>` 要素

<background> 要素は <execNative> 要素の子です。この要素が存在する場合、コマンドをバックグラウンドプロセスとして実行する必要があることを示します。この要素には属性も子要素もありません。

<background> 要素が指定された <execNative> の場合、以下の制限が適用されます。

<successCriteria> は指定の必要はありません。ステップは、バックグラウンドプロセスを開始する上で何も問題が存在しなかった場合には成功します。指定すると、コマンドをバックグラウンドプロセスとして実行するために使用されるスクリプトに照らして <successCriteria> のテストが行われます。
実行されるコマンドの標準出力または標準エラー出力はキャプチャされません。

ブラウザインタフェースの「details」を参照すると、終了ステータス 0 と、空の標準出力、および標準エラー出力が表示されます。しかし、バックグラウンドでネイティブコマンドを開始する際に問題があった場合は、別の終了ステータスが表示されます。その値はエラーの特性と診断出力に応じて決まります。
<outputFile> および <errorFile> 要素を指定する必要があります。指定したファイルがすでに存在する場合、それらは上書きされます。

`<outputFile>` 要素

<outputFile> 要素は <execNative> 要素の子です。<outputFile> 要素は、実行されるコマンドの標準出力が格納される、エージェント上のローカルファイルのパスを指定します。ローカルファイルのパスは、<outputFile> 要素の name 属性を使用して指定します。相対パスは、コマンドの作業ディレクトリに相対的であると解釈されます。

<background> 要素を指定する場合は、<outputFile> 要素を指定する必要があります。

<outputFile> を指定せず、<successCriteria> 要素で outputMatches も指定しないと、コマンドの出力は格納されずに消失します。outputMatches を指定すると、標準出力は一時ファイルに格納され、コマンドの実行後そのファイルが削除されます。

`<outputFile>` 要素属性

<outputFile> 要素には 1 つの必須属性 name があり、これはコマンドの標準出力の書き込み先となるファイル名です。この値は、空でない文字列にする必要があります。この属性は、単純置換変数を参照できます。

`<errorFile>` 要素

<errorFile> 要素は、実行されるコマンドのエラー出力を格納する、エージェント上のローカルファイルのパスを指定します。ローカルファイルのパスは、<errorFile> 要素の name 属性を使用して指定します。相対パスは、コマンドの作業ディレクトリに相対的であると解釈されます。

<background> 要素を指定する場合は、<errorFile> 要素を指定する必要があります。

<errorFile> を指定せず、<successCriteria> 要素で errorMatches も指定しないと、コマンドの出力は格納されずに消失します。errorMatches を指定すると、エラー出力は一時ファイルに格納され、コマンドの実行後そのファイルが削除されます。

`<errorFile>` 要素属性

<errorFile> 要素には 1 つの必須属性 name があり、これはコマンドの標準エラー出力の書き込み先となるファイル名です。この値は、空でない文字列にする必要があります。この属性は、単純置換変数を参照できます。

`<inputText>` 要素

<inputText> 要素は <execNative> 要素の子です。この子要素は、コマンドの標準入力として使用する必要がある任意のテキストを指定します。このテキストは、この要素のコンテンツとして指定されます。

<execNative>
    <inputText>
        ls -l | fgrep `*test*' | sort -u > file.out
    </inputText>
    <command exec=”sh”/>
</execNative>

<inputText> 要素の本体は、CDATA セクションで囲むことができます。これにより、入力フォーマットを保持するとともに、文字 & や < を含む入力で発生しうる解析エラーを防ぐことができます。

<inputText> を指定すると、<execNative> ステップの XML を生成する際に常に CDATA セクション内に包含されます。<inputText> 内の文字はすべて、実行されるコマンドに標準入力として渡されます。<inputText> に空白文字だけを含めると、それらの空白文字は指定されているとおりに、実行されるコマンドに渡されます。

<inputText> のコンテンツは config 生成されます。

<inputText> 要素に属性はありません。

`<inputFile>` 要素

<inputFile> 要素は <execNative> の子要素です。この子要素は、実行されるコマンドの標準入力として使用されるコンテンツが入った、Remote Agent 上のローカルファイルのパスを指定します。ローカルファイルのパスは、<inputFile> 要素の name 属性を使用して指定します。

注 –

<inputFile> 要素は、<execNative> コマンド内で <inputText> 要素と併用することはできません。

`<inputFile>` 要素属性

<inputFile> 要素には 1 つの必須属性 name があり、これはコマンドに対する標準入力として動作するファイルです。この値は、空でない文字列にする必要があります。相対パスを指定した場合、コマンドの作業ディレクトリに対して相対的であると解釈されます。この属性は、単純置換変数を参照できます。

`<exec>` 要素

<execNative> ステップには <exec> 要素を 1 つしか含めることができません。<exec> 要素は、実行されるネイティブコマンドの詳細を指定します。

<exec> 要素には次の属性が含まれます。

実行するコマンドの名前を指定する cmd 属性
cmd コマンドの各引数用の、入れ子になった一連の <arg> 要素

<execNative> は、cmd により指定されたコマンドを、指定された引数を順に使用して実行します。

次に、<execNative> ステップが ps -fu sps コマンド実行する例を示します。

<execNative>
    <exec cmd=”ps”>
        <arg value=”-fu”/>
        <arg value=”sps”/>
    </exec>
</execNative>

<exec> 要素にはオプションの子要素 <arg> があります。実行するコマンドに対する各引数に 1 つの <arg> 要素を指定します。

<arg> 要素には 1 つの必須属性 value があり、この属性は引数値です。この引数は、<arg> がコマンド要素の n 番目の子であるコマンドに n 番目の引数として渡されます。この属性は、単純置換変数を参照できます。

`<exec>` 要素属性

<exec> 属性には 1 つの必須属性 cmd があり、この属性は実行するコマンドのパスです。指定したパスが絶対パスでない場合、Remote Agent に対して設定された、プラットフォーム指定の PATH 環境変数を使用してコマンドの検索が行われます。この値は、空でない文字列にする必要があります。この属性は、単純置換変数を参照できます。

`<shell>` 要素

<shell> 要素は <execNative> の子要素です。<shell> 要素のコンテンツは、実行されるコマンドを指定します。実行されるコマンドは、cmd 属性で指定されるインタプリタによって解釈されます。したがって、そのコマンドはプラットフォームの sh -c “command” 構文を使用して実行されます。この書式では、コマンドの実行に使用するシェルコマンドを示すために cmd 属性を指定する必要があります。

次に例を示します。

<execNative>
    <shell cmd=”/usr/bin/bash -c”>
        ls -l | fgrep `*test*' | sort -u > file.out
    </shell>
</execNative>

前に示した <execNative> の例では、次のコマンドを実行していました。

/usr/bin/bash -c `ls -l | fgrep `*test*' | sort -u > file.out'

書式を保持するとともに XML の解析問題を回避するため、<execNative> ステップから XML 表現を生成する際には常に CDATA 要素内にコマンドのテキストコンテンツが包含されます。

コマンド文字列を空の状態にしたり、空白文字だけを入れたりすることは認められません。コマンド文字列は、(周囲の空白も含め) 指定されているとおりにシェルに送られます。

<shell> 要素のコンテンツは config 生成されます。

`<shell>` 要素属性

<shell> には 1 つの必須属性 cmd があり、この属性は sh -c 構文内のシェルコマンドです。この文字列に、埋め込みの引用符文字を含めないでください。この文字列は、空白を区切りとして使用して、シェル名と引数を取得するために解析されます。たとえば、/usr/bin/bash -c は空でない文字列にします。この属性は、単純置換変数を参照できます。

`<successCriteria>` 要素

<successCriteria> 要素は <execNative> の子要素です。この子要素は、 <execNative> ステップが正常に実行されたかを評価するために使用される基準を指定します。この要素が指定されない場合のデフォルト値は <successCriteria status=”0”/> です。

空の <successCriteria> を指定すると、<successCriteria> は無視されます。

<successCriteria/> を指定した場合、コマンドがどのような出力または終了コードを生成した場合でも、ステップは常に成功します。

`<successCriteria>` 要素属性

<successCriteria> 要素には次のオプション属性があります。status、outputMatches、および errorMatches 属性の中から複数の属性が指定されると、それらの AND (論理積) がとられます。

status – 整数型のオプション属性で、コマンドの適切な終了ステータス。この値は正の整数でなければなりません。
outputMatches – オプション属性で、コマンドによって生成された標準出力を照合する正規表現。この値は、空でない文字列にする必要があります。この属性は、単純置換変数を参照できます。
errorMatches – オプション属性で、コマンドによって生成された標準エラー出力を照合する正規表現。この値は、空でない文字列にする必要があります。この属性は、単純置換変数を参照できます。
inverse – ブール型のオプション属性で、true に設定すると、<successCriteria> で指定された各条件が無視されます。デフォルト値は、false です。つまり、<successCriteria> の各属性で指定された条件が満たされない場合だけステップは成功します。

たとえば、次の <successCriteria> を持つ <execNative> ステップが成功するのは、status が 1 ではなく、標準出力が bin に一致せず、標準エラーが none に一致しない場合です。
<successCriteria status=”1” outputMatches=”bin” errorMatches=”none” inverse=”true”/>
inverse 属性だけを含む <successCriteria> 要素は、inverse 属性なしで保存されます。つまり、次のように指定すると、要素は <successCriteria/> として格納され、<successCriteria> 要素は無視されます。
<successCriteria inverse=”true”/>

`<if>` ステップ

このステップは、ステップブロックを条件付きで実行するために使用されます。このステップには属性がありません。子要素は <condition> 、<then>、および <else> です。<condition> 要素と <then> 要素は同時に出現する必要があります。<else> 要素を指定する場合、この要素は 1 回しか出現できません。

<condition> 要素のコンテンツが true に評価される場合、<then> ブロックのステップは実行されます。true に評価されない場合、 <else> ブロックのステップが実行されます (存在する場合)。

例 2–1 `<if>` ステップの使用方法

以下に、条件付きで再起動するために使用される <if> ステップの例を示します。

<if>
    <condition><istrue value=":[restart]"/></condition>
    <then>
        <call blockName="restart"/>
    </then>
</if>

`<condition>` 要素

<condition> 要素は <if> ステップの子要素で、ブール式を指定します。この要素に属性はありません。この要素は、ブール演算子の子要素を 1 つだけ含む必要があります。詳細は、「ブール型演算子」を参照してください。

`<then>` 要素

<then> 要素は <if> ステップの子要素です。この要素は、関連付けられた条件が true の場合に実行するステップを指定します。<then> 要素には、<if> ステップを含むブロックのスコープ内で許可されるステップをいくつでも含めることができます。

`<else>` 要素

<else> 要素は <if> ステップの子要素です。この要素は、関連付けられた条件が true でない場合に実行するステップを指定します。<else> 要素には、<if> ステップを含むブロックのスコープ内で許可されるステップをいくつでも含めることができます。

`<pause>` ステップ

<pause> ステップは、指定された期間、プランの実行を一時的に中止します。<pause> は、必要なサービスが起動されたあと、このサービスがオンラインになるのをプランに待機させるために使用できます。

`<pause>` ステップ属性

<pause> 要素は positiveInteger 型の 1 つの必須属性 delaySecs を持ちます。この属性は待機する時間 (秒数) を指定します。

`<processTest>` ステップ

<processTest> ステップは、ターゲットホストで特定のプロセスが実行されているかを調べるために使用されます。目的のプロセスが存在しない場合、ステップは失敗し、実行が停止します。

注 –

このステップは、UNIX® システムでの使用を意図したものです。

`<processTest>` ステップの属性

<processTest> ステップには次の属性があります。

delaySecs – positiveInteger 型の必須属性で、プロセスが存在するかどうかをテストする前に待機する時間 (秒数)。
timeoutSecs – positiveInteger 型の必須属性で、プロセスがオンラインになるのを待機する時間 (秒数)。この時間が経過すると失敗になります。この時間は、遅延時間が経過したあとからカウントされます。
processNamePattern – 必須属性で、指定のプロセス名の照合に使用する glob スタイルパターン。この属性は、単純置換変数を参照できます。
user – オプション属性で、プロセス所有者の名前を照合するために使用される glob スタイルパターン。この属性を指定しないと、プロセス所有者はテストの一環と見なされません。この属性は、単純置換変数を参照できます。

`<raise>` ステップ

<raise> ステップは、常に失敗するステップです (<try> ステップにおける捕捉と処理は可能)。このステップには「message」という属性だけが存在し、子要素はありません。

<raise> ステップは、人為的なステップを構築することなくエラー状況を示す手段として使用されます。このステップの出現がもっとも多いのは <catch> ブロック内であり、クリーンアップ後のエラー状況を伝えるために使用されます。

`<raise>` ステップの属性

<raise> 要素には 1 つのオプション属性 message があり、この属性はエラー状況を説明するメッセージです。デフォルトは、メッセージはシステムで指定された一般的なメッセージです。この属性は、単純置換変数を参照できます。

例 2–2 `<raise>` ステップの使用方法

以下の例は、ログ内にエラーを見つけたあと <catch> ブロック内からエラー状況を再伝達するために <raise> ステップをどのように使用するかを示しています。

<control blockName="default">
    <try>
        <block>
            <!-- ここで任意の処理が行われます -->
        </block>
        <catch>
            <!-- ログのエラーに注意してください -->
            <execNative>
                <exec cmd="appendLog">
                    <arg value="an error occurred"/>
                </exec>
            </execNative>
            <!-- rethrow エラーです -->
            <raise/>
        </catch>
    </try>
</control>

MS Windows:`<reboot>` ステップ

このステップは、プランの残り部分を続行する前にエージェントにリブートを行わせます。このステップは、Microsoft Windows (MS Windows) ベースのシステム上でしか使用できません。MS Windows 以外のプラットフォームで検出された場合は、エラーが発生します。Master Server と同じホスト上に存在するエージェントをリブートした場合もエラーとなります。ここで説明しているエラーはプリフライトエラーです。

MS Windows:`<reboot>` ステップの属性

<reboot> ステップには positiveInteger 型の 1 つのオプション属性である timeout があります。この属性はサーバーのリブートを待機する最長時間 (秒数) です。この属性を指定しないと、プランの <execNative> タイムアウト期間が適用されます。

`<retarget>` ステップ

このステップは、一連のステップの実行対象を変更します。retarget ステップは入れ子にすることができます。

<retarget> ステップには次の子要素があります。

<varList> – オプション要素で、包含されたステップで使用できるローカル変数の一覧。これらの変数は、新しいホストのスコープ内で評価されます。この要素を指定する場合、この要素は 1 回しか出現できません。
Steps – オプション要素で、新しいホスト上で実行するステップが含まれます。<retarget> ステップを含むブロックのスコープ内で許可される任意のステップを指定できます。複数のステップを指定できます。例については、例 2–3を参照してください。

`<retarget>` ステップの属性

<retarget> ステップには必須属性 host があり、この属性は包含されたステップの実行対象となるホストです。この属性は、単純置換変数を参照できます。

この属性は、各種のコンポーネントターゲッター要素のほか、<retarget> ステップでも使用できます。この属性の値はホストの名前であり、置換変数参照を含むことができます。また、シンボリック名「/」を含めて現在の実行対象のルート物理ホストを参照することも、あるいは「..(/..)*」を含めて現在の実行対象の親ホストを参照することもできます。

注 –

host 属性をコンポーネントターゲッター内に指定した場合、意味的には、包含するステップを <retarget> ステップ内に含めたのと同じになります。

`<retarget>` ステップの実行セマンティクス

<retarget> ステップが検出される場合、まず呼び出し側の現在のホストのコンテキストで「host」属性を評価します。

「host」属性の値が現在のホストの名前と異なる場合、以下のステップが実行されます。

ホスト名を実際のホストに解決します。そのようなホストが存在しない場合、エラーが発生します。
プランのフォルダ、またはこのステップを含むコンポーネントに関して、現在のユーザーが、そのホストにおいて「実行」アクセス権を所有しているかを検証します。所有していない場合、エラーが発生します。
ホストのルート物理ホストに関して、以下の条件が満たされていることを検証します。
- Remote Agent が含まれている。
- ルート物理ホストに接続できる。
- ルート物理ホストが最新の状態で準備が整っている。
これらの条件が満たされない場合、エラーが発生します。
以前にアクセスしたすべてのホストでロックを保持したまま、このホストでロックを取得します。現在の実行スレッドがすでにホストをロックしている場合、この処理は事実上ノーオペレーション (空命令) となります。ホストがすでにほかの実行スレッドによってロックされている場合、この処理はホストのロックが解除されるまでブロックします。ロック要求のためにデッドロックが起きた場合は、エラーが発生します。
そのホストが再設定され、新しい「現」ホストになります。「物理」ホストは、新しい「現」ホストに基づいて再設定されます。「初期」ホストは変化しません。

上記のステップが完了したところで、<varList> 要素の変数が新しい現ホストのコンテキストで評価されます。ローカル変数は、包含するスコープの変数を隠蔽することができます。続いて、各ステップが新しい現ホストのコンテキストで実行されます。

最後に、対象変更の処理によって現ホストが変わった場合には、そのロックが適宜解除され、その現ホストが呼び出し側の現ホストとして再設定されます。現在の実行スレッドでホストが以前にロックされている場合は、ロックを初めに取得したブロックが完了するまでロックしたままとなります。

空の <retarget> ブロックを使用することにより、現在のユーザーが適切なアクセス許可を持っていることと、ホストの準備が適切に行われていることをあらかじめ検証できます。

例 2–3 `<retarget>` ステップの使用方法

以下に、WebLogic 管理対象サーバー上で使用できる「再起動」制御サービスの例を示します。この制御サービスは、管理サーバー上で制御を呼び出して管理対象サーバーを「停止」し、続いてローカルサーバーで呼び出しを行なってサーバーを起動することによって実施されます。

「adminHostName 」変数は、呼び出し側の現ホスト (これは管理対象サーバーを含んでいる仮想ホストと見なされる) で評価されます。「domainName」変数は、新しいターゲットホスト (これは管理サーバーを含んでいる仮想ホストと見なされる) で評価されます。ADMIN_SERVER コンポーネントも、新しいターゲットホストで解決処理されます。

<control name="restart">
    <varList>
        <var name="adminHostName" default=":[target:adminHostName]"/>
    </varList>
    <retarget host=":[adminHostName]">
        <varList>
            <var name="domainName" default=":[target:domainName]"/>
        </varList>
        <call blockName="stopServer">
            <argList serverName=":[serverName]"
	      domainName=":[domainName]"/>
            <installedComponent name="ADMIN_SERVER"/>
        </call>
    </retarget>
    <call blockName="start"/>
</control>

`<sendCustomEvent>` ステップ

<sendCustomEvent> ステップは、特定のメッセージを使用してカスタムイベントを生成するために使用されます。このステップを通知規則モジュールと併用することで、特定のホストでこのステップが検出されるたびに電子メールを送信できます。

`<sendCustomEvent>` ステップの属性

<sendCustomEvent> ステップには 1 つの必須属性 message があり、この属性はイベントテキストとして含めるメッセージです。この属性は、単純置換変数を参照できます。

`<transform>` ステップ

<transform> ステップは、ターゲットホスト上にあるファイルのテキストベース変換を行うために使用されます。現時点では、Perl タイプおよび XSLT ベースの変換がサポートされています。

<transform> の子要素は、入力ファイルに適用される変換を指定します。これらの子要素は、以下のどれでもかまいません。

入力ソースに適用する XSLT 変換を定義する単一の <stylesheet> 要素
入力ソースに順次適用する Perl に似た置換パターンを定義する 1 つ以上の <subst> 要素
変換を含んでいる外部ファイルを命名する単一の <source> 要素
空。これは、入力ファイルのコンテンツが出力ファイルに直接コピーされることを意味します。

これは、zip アーカイブから抽出する場合または zip アーカイブに書き込む場合に便利です。

`<transform>` ステップの属性

<transform> ステップには次の属性があります。

input – オプション属性で、変換の適用先である、ターゲットホスト上のファイルの一般パス。この属性を指定しないと、入力は出力ファイルから読み取られます。この属性は、単純置換変数を参照できます。
output – 必須属性で、変換結果の書き込み先である、ターゲットホスト上のファイルの一般パス。この属性は、単純置換変数を参照できます。

input 属性と output 属性は、同じファイルまたは個別のファイルを参照できます。これらの属性の値は、zip アーカイブ (または zip の派生フォーマットである JAR など) をディレクトリ要素として含むことができる一般パスです(例: webapp/myapp.jar/config.xml)。

`<stylesheet>` 要素

<stylesheet> 要素は <transform> ステップの子であり、入力ソースに適用する XSLT 変換を指定します。特定の <transform> 要素の子として指定できるのは <stylesheet> 要素 1 つであり、<stylesheet> 要素をほかの子要素と併用することはできません。

<stylesheet> 要素は、名前空間 http://www.w3.org/1999/XSL/Transform で定義されている XSLT バージョン 1.0 要素です。詳細は、http://www.w3.org/TR/xslt.html の『XSL Transformations (XSLT)』仕様のバージョン 1.0 を参照してください。<transform> 要素の子として受け入れられるのは、XSLT <stylesheet> 要素だけです。XSLT 仕様の節 2.3 で説明された XSLT シノニム <transform>、単純化された XSLT 変換構文とも、<transform> 要素の子としてはサポートされません。

<stylesheet> 要素本体には、本体が有効な XSLT であるかぎり、初めに変数置換を行うことなく置換変数参照を含めることができます。

<stylesheet> 要素が変換として使用される場合、入力ファイルは XML 形式でなければなりません。詳細は、『XSL Transformations (XSLT)』仕様のバージョン 1.0 を参照してください。

例 2–4 `<stylesheet>` 要素の使用方法

<transform output="/etc/hosts">
    <xsl:stylesheet version="1.0"
      xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
        <xsl:template match="/">
            <xsl:for-each select="a">
                <xsl:value-of select="b"/>
            </xsl:for-each>
        </xsl:template>
    </xsl:stylesheet>
</transform>

`<subst>` 要素

<subst> 要素は <transform> ステップの子であり、変換として適用する Perl に似た置換パターンを指定します。複数の <subst> 要素を <transform> 要素の子として指定できますが、ほかの子要素とは併用できません。複数の <subst> 要素が出現する場合、それらは順次適用されます。

入力ファイル内に出現するパターンは、1 行内に複数出現している場合も含めすべて置換されます。

サポートされる構文の詳細は、Java ドキュメント (class java.util.regex.Pattern) を参照してください。

`<subst>` 要素属性

<subst> 要素には次の属性があります。

match – 必須属性で、入力後に検索される Perl に似た正規表現 (大文字小文字の区別がなされる)。この属性は、単純置換変数を参照できます。
replace – 必須属性で、「match」で指定されたパターンが出現するごとに置換される Perl に似た置換値。この値は一語一語解釈されるのではなく、構成体 $n が検索表現内で n 番目に出現する括弧付きの表現として解釈されます。この属性は、単純置換変数を参照できます。

例 2–5 `<subst>` 要素の使用方法

以下の変換は、ファイル /etc/hosts 内で、文字列 127.0.0. xxx をすべて 10.10.0.xxx に変換します。

<transform output=”/etc/hosts”>
    <subst match="127\.0\.0\.(\d+)"
    replace="10.10.0.$1"/>
</transform>

`<source>` 要素

<source> 要素は <transform> ステップの子であり、入力ファイルに適用する変換が入っている、ターゲットホスト上の外部ファイルを指定します。特定の <transform> 要素の子として指定できるのは <source> 要素 1 つであり、<source> 要素をほかの子要素と併用することはできません。

指定されたソースファイルに対して <transform> ステップの一部として config 生成が行われることはありません。しかし、指定されたソースファイルが、コンポーネントインストールの一部として配備された config 型のリソースファイルである場合があります。このようなケースでは、ソースファイルに含まれる置換変数は、ソースファイルが配備された際に置換されています。

`<source>` 要素属性

<source> 要素には次の属性があります。

type – 必須属性で、指定されたファイル内に含まれる変換のタイプ。次の値が使用できます。
- PERL – <subst> 要素による変換に類似した Perl に似た変換。この場合、指定されるファイルは以下のような形式をとる必要があります。
  <?xml version='1.0'?> <transform> <subst match="127\.0\.0\.(\d+)" replace="10.10.0.$1"/> </transform>
  Perl 型の外部変換ファイルは、任意の数の <subst> 要素を含むことができます。
- XSLT – XSLT 変換。この場合、指定されたファイルには、名前空間 http://www.w3.org/1999/XSL/Transform で定義されているように、標準の XSLT バージョン 1.0 変換が含まれます。XSLT <stylesheet> 要素しか許可しないインライン変換と異なり、外部ソースファイルに含まれる XSLT 変換は任意の有効な最上位 XSLT 変換要素を含むことができます。このような要素としては、 <stylesheet>、<transform>、および単純化された XSLT 構文などが該当します。単純化された XSLT 構文は、XSLT 仕様の節 2.3 で説明されています。
name – 必須属性で、変換を含む、ターゲットホスト上のファイルの名前。ファイルのコンテンツは、「type」属性で定義された型に一致する必要があります。この名前は、ディレクトリ要素として zip アーカイブを含むことはできません。この属性は、単純置換変数を参照できます。

`<try>` ステップ

<try> ステップは、ステップブロックの典型的なエラー処理とクリーンアップロジックを指定するために使用されます。このステップには属性がありません。このステップには次の 3 つの子要素、<block>、<catch>、および <finally> があります。

<try> ステップは次のように実行されます。

<block> 要素内のステップは、すべてが完了するか、ステップのどれかが失敗するまで順に実行されます。各ステップの失敗は、Plan Executor により決定されます。
<catch> 要素が定義されており、かつプランの中断 (abort) またはプランのタイムアウト以外のステップエラーでブロック要素の実行が終了した場合にかぎって、すべてが完了するかあるいはステップのどれかが失敗するまで <catch> 要素内のステップが順に実行されます。
<finally> 要素が定義されている場合、そのステップはそれらがすべてが完了するかステップのどれかが失敗するまで順に実行されます。これは、プランの中断またはプランのタイムアウトのために先の 2 つの要素のどちらか一方が停止しないかぎり、それらの要素の成否に関係なく発生します。
プランの中断またはプラン (ステップではなく) のタイムアウトのために、包含されるステップのどれかが失敗する場合、包含されるほかのステップは実行されず、<try> ステップの実行はエラーを示して終了します。

<catch> 要素は、<block> 要素内で発生するエラーの抑制と、これらのエラーからの回復のために使用されます。<finally> 要素は、典型的なエラーが検出されるかどうかにかかわらず、無条件でクリーンアップを行うために使用されます。

<try> ステップは、以下のように成否が決まります。

<try> ステップに <finally> 要素だけが含まれる場合、<block> または <finally> 要素の実行が失敗すると、このステップは失敗します。
<try> ステップに <catch> 要素だけが含まれる場合、このステップが失敗するのは、<catch> 要素の実行が行われて失敗した、あるいはプランの中断またはプランのタイムアウトのために <block> 要素が失敗した場合のみです。
<try> ステップに <catch> および <finally> 要素の両方が含まれる場合、このステップは以下の状況のいずれかが発生するときだけ失敗します。
- <catch> または <finally> 要素が実行されて失敗した場合。
- <finally> 要素が実行されて失敗した場合。
- プランの中断またはプランのタイムアウトのために <block> 要素が失敗した場合。

以上のことから、<block> 要素の失敗は <catch> 要素の存在で抑制できると言えます。

<try> ステップには次の子要素があります。

<block> – 必須要素で、初めに実行されるステップから構成されています。
<catch> – オプション要素で、典型的なエラー時に実行されるステップが含まれています。<finally> 要素が指定されない場合には、指定する必要があります。この要素を指定する場合、この要素は 1 回しか出現できません。
<finally> – オプション要素で、典型的なエラーであるかどうかにかかわらず実行されるステップが含まれます。<catch> 要素が指定されない場合には、指定する必要があります。この要素を指定する場合、この要素は 1 回しか出現できません。

`<block>` 要素

<block> 要素は、<try> ステップの子要素です。この要素は、<try> ステップによって実行される主要なステップを指定します。<block> 要素には、<try> ステップを含んでいるブロックのスコープ内で許可される 1 つ以上のステップが含まれます。

`<catch>` 要素

<catch> 要素は、<try> ステップの子要素です。この要素は、<block> 要素のステップを実行している際に典型的なエラーが発生する場合に実行するステップを指定します。<catch> 要素には、 <try> ステップを含んでいるブロックのスコープ内で許可される任意の数のステップを含めることができます。

<catch> 要素には、<block> 要素の典型的なエラーを抑制するという機能と、典型的なエラー回復作業を定義するという機能があります。この要素は空にすることができます。空にすると、<catch> は典型的なエラーの抑制だけを行います。

`<finally>` 要素

<try> ステップの子要素です。<finally> は、<try> または <catch> ステップ内で典型的なエラーが以前に発生したかどうかにかかわらず実行するステップを指定します。典型的なエラーには、プランの中断とプランのタイムアウトがあり、これらのエラーが発生した場合、<finally> 要素のステップはスキップされます。<finally> には、<try> ステップを含んでいるブロックのスコープ内で許可される任意の数のステップを含めることができます。

<finally> 要素は、エラーを考慮することなく常に実行する必要があるクリーンアップステップを指定するために使用されます。エラーに対応してクリーンアップステップを実行するには、代わりに <catch> 要素内にクリーンアップステップを配置します。

例 2–6 `<try>` ステップの使用方法

以下の例では、コンポーネントのインストールは、再起動があとに続くリソース配備で構成されています。このケースでは、コンポーネントのインストールが完了したと見なされるのは、そのリソースが配備され、再起動時における失敗がそのインストール状態に影響を与えない場合だけです。典型的なエラーは、以下のように再起動時に抑制できます。

<installSteps blockName="default">
    <deployResource/>
    <try>
        <block>
            <call blockName="restart"><thisComponent/></call>
        </block>
        <catch/><!-- すべての典型的なエラーを抑制します -->  
    </try>
</installSteps>

<try> ブロックは、インテリジェントな自動アップグレードのモデル化に使用できます。バージョン 1.1 のコンポーネントが 2 つの異なるインストールルーチンを持っているとします。あるユーザーはコンポーネントのフレッシュインストールを行い、そのコンポーネントのバージョン 1.0 が以前にインストールされていた場合、もう 1 人のユーザーがアップグレードインストールを行います。この状況は、以下のように単一のインストールブロックとしてモデル化できます。

<installSteps blockName="default">
    <try>
        <block>
          <checkDependency>
              <installedComponent name="foo" version="1.0"/>
          </checkDependency>
          <!-- 1.0 のインストールが存在するため、アップグレードを行います -->
        </block>
        <catch>
          <!-- 1.0 のインストールが存在しないため、フレッシュインストールを行います -->
        </catch>
    </try>
</installSteps>

<finally> ブロックは、通常、一時リソースのクリーンアップに使用されます。次の例では、一時ファイルの作成、処理、および削除が行われます。

<control blockName="default">
    <varList>
        <var name="file" default="/tmp/file.txt"/>
    </varList>
    <execNative outputFile=":[file]">
        <exec cmd="ls"><arg value="-l"/></exec>
    </execNative>
    <try>
        <block>
            <!-- 何らかの方法でファイルを処理します -->
        </block>
        <finally>
            <execNative>
                <exec cmd="rm"><arg value=":[file]"/></exec>
            </execNative>
        </finally>
    </try>
</control>

`<urlTest>` ステップ

このステップは、特定の URL のコンテンツが予期されたパターンに一致するかどうかを検証するために使用されます。妥当なパターンに一致しない場合、ステップは失敗し、実行が停止します。

`<urlTest>` ステップの属性

<urlTest> ステップには次の属性があります。

delaySecs – A required attribute of type positiveInteger 型の必須属性で、URL コンテンツのテストを実施する前に待機する時間 (秒数)。
timeoutSecs – positiveInteger 型の必須属性で、URL コンテンツの受け取りを待機する時間 (秒数)。この時間を過ぎると失敗します。この時間は、遅延時間が経過したあとからカウントされます。
URL – 必須属性で、コンテンツのテストが行われる URL。現在サポートされているのは HTTP プロトコルだけです。この属性は、単純置換変数を参照できます。
pattern – 必須属性で、テストされる URL のコンテンツに一致すると予測される glob スタイルのパターン。この値は複数バイト符号化をサポートしています。この属性は、単純置換変数を参照できます。

インストール済みコンポーネントターゲッター

この節では、特定のインストール済みコンポーネントを包含ステップ (制御サービスコールなど) の対象として特定する要素を示します。対象となるすべてのステップですべてのターゲッターを使用できるわけではありません。各ターゲッターは、それ自体が使用できるステップを指定します。

`<installedComponent>` インストール済みコンポーネントターゲッター

<installedComponent> 要素は、ターゲットホスト上にインストールされていると想定される特定のインストール済みコンポーネントを特定します。

この要素は、<checkDependency>、<createDependency>、<call>、<uninstall>、および <addSnapshot> ステップのターゲッターとして使用できます。

このターゲッターは指定されたコンポーネントを直接照合するもので、指定されたコンポーネントの派生インスタンスの照合には使用できません。特定の型から派生したコンポーネントを対象とする場合は、<systemType> ターゲッターを使用してください。

`<installedComponent>` ターゲッターの属性

このターゲッターには次の属性があります。

name – entityName 型の必須属性で、インストール済みコンポーネントの名前。
path – pathReference 型のオプション属性で、コンポーネントのパス。この属性を指定しないと、包含するエンティティのパスが使用されます。
version – version 型のオプション属性で、インストール済みコンポーネントのバージョン。この属性を指定しないと、バージョンを考慮せず、最後にインストールされたコンポーネントが使用されます。
versionOp – オプション属性で、version 属性と、ターゲットホストにインストールされているコンポーネントのバージョンを比較する際に使用する演算子を指定します。複数のインストール済みコンポーネントが適用される場合、最後にインストールされたコンポーネントが使用されます。使用できる値は、=、>=、および > です。

デフォルトでは >= 演算子が使用されます。version を指定しないと、versionOp は無視されます。
onlyCompat – オプション属性で、照合を行うコンポーネントを指定します。

値が true である場合、バージョン version のコンポーネントと呼び出し互換性のあるコンポーネントだけを照合する必要があります。バージョン version のコンポーネントが存在する必要があります。デフォルトでは値は false です。version を指定しないと、この要素は無視されます。
installPath – オプション属性で、インストール済みコンポーネントのインストールパス。この属性を指定しないと、任意のパスの一番新しいインストール済みコンポーネントが使用されます。この値は、コンポーネントの解決処理の前に共通書式に変換されます。この属性は、単純置換変数を参照できます。
host – オプション属性で、コンポーネントがインストールされているホスト。デフォルトでは、host は現在のホストです。host 属性の詳細については、「<retarget> ステップの属性」を参照してください。この属性は、単純置換変数を参照できます。

`<systemService>` インストール済みコンポーネントターゲッター

<systemService> 要素は、現在の物理ホストにインストールされていると想定される特定のシステムサービスコンポーネントを特定します。システムサービスがプラグインにより定義されている場合は、pluginName# serviceName のように、サービス名にはプラグイン名を接頭辞として付ける必要があります。

この要素は、<checkDependency>、<createDependency>、<call>、<uninstall>、および <addSnapshot> ステップのターゲッターとして使用できます。

<systemService> ターゲッターを使用すると、暗黙に現在のホストのルート物理ホストに対象が変更されます。別のホスト上のシステムサービスを対象とする必要がある場合は、<retarget> ステップを使用する必要があります。このステップを使用しないかぎり、<systemService> ターゲッター内で新しいホストを指定することはできません。

`<systemService>` ターゲッターの属性

<systemService> ターゲッターには systemName 型の 1 つの必須属性 name があり、これはシステムサービスコンポーネントの名前です。システムサービスがプラグインにより定義されている場合は、pluginName# serviceName のように、システムサービス名にはプラグイン名を接頭辞として付ける必要があります。

`<systemType>` インストール済みコンポーネントターゲッター

<systemType> 要素は、ターゲットホスト上にインストールされていると想定される特定の型のインスタンスであるコンポーネントを特定します。指定した基準に複数のインストール済みコンポーネントが一致する場合、一番最近インストールされたコンポーネントが使用されます。

<systemType> 要素は、<checkDependency>、<createDependency>、<call>、<uninstall>、および <addSnapshot> ステップのターゲッターとして使用できます。

`<systemType>` ターゲッターの属性

<systemType> ターゲッターには次の属性があります。

name – systemName 型の必須属性で、システム型コンポーネントの名前。システム型がプラグインにより定義されている場合は、pluginName# typeName のように、システム型名にはプラグイン名を接頭辞として付ける必要があります。
installPath – オプション属性で、必要なコンポーネントのインストールパス。この値は、コンポーネントの解決処理の前に共通書式に変換されます。この属性は、単純置換変数を参照できます。
host – オプション属性で、コンポーネントがインストールされるホストです。デフォルトでは、host は現在のホストです。host 属性の詳細については、「<retarget> ステップの属性」を参照してください。この属性は、単純置換変数を参照できます。

`<thisComponent>` インストール済みコンポーネントターゲッター

<thisComponent> 要素は、ステップを含むコンポーネントを、ステップの対象として使用する必要があることを指定します。このターゲッターを使用できるのは、コンポーネント内に含まれるステップだけです。この要素には属性がありません。

<thisComponent> 要素は、<call>、<uninstall>、および <addSnapshot> ステップのターゲッターとして使用できます。

リストされたステップにコンポーネントターゲッター要素が含まれない場合、デフォルトで <thisComponent> が使用されます。

`<superComponent>` インストール済みコンポーネントターゲッター

<superComponent> 要素は、ステップを含むコンポーネントのベースコンポーネントを、ステップの対象として使用する必要があることを示します。このターゲッターを使用できるのは、派生コンポーネント内に含まれるステップだけです。

<superComponent> 要素は、<call>、<uninstall>、および <addSnapshot> ステップのターゲッターとして使用できます。この要素には属性がありません。

このターゲッターは、派生コンポーネントが無効にする場合でも、常にベースコンポーネントによる該当ステップの定義にバインドします。

`<nestedRef>` インストール済みコンポーネントターゲッター

<nestedRef> 要素は、現在の複合コンポーネントによって宣言または継承が行われた、入れ子になったコンポーネント参照を特定します。このターゲッターを使用できるのは、複合コンポーネント内のステップだけです。

<nestedRef> 要素は、<checkDependency>、<call>、<uninstall> 、および <addSnapshot> ステップのターゲッターとして使用できます。

この際、指定されたコンポーネント参照が呼び出し側コンポーネントによってすでにインストールされていると想定され、インストールされていない場合はエラーが生成されます。入れ子になったコンポーネント参照が現在のターゲットホスト以外のホストにインストールされた場合は、<nestedRef> ターゲッターを使用することで、関連付けられているステップの対象がそのホストに暗黙に変更されます。

`<nestedRef>` ターゲッターの属性

<nestedRef> ターゲッターには identifier 型の 1 つの必須属性 name があり、これは当該コンポーネント内の入れ子になったコンポーネント参照の名前です。

`<allNestedRefs>` インストール済みコンポーネントターゲッター

<allNestedRefs> 要素は、現在の複合コンポーネントによって宣言または継承が行われた、入れ子になったコンポーネント参照をすべて特定します。このターゲッターを使用できるのは、複合コンポーネント内のステップだけです。

この要素は、<call>、<uninstall>、および <addSnapshot> ステップのターゲッターとして使用できます。

このターゲッターは、任意の数のコンポーネントを特定できます。コンポーネントがまったく特定されない場合、ステップはノーオペレーション (空命令) となります。このターゲッターが複数のコンポーネントを特定する場合、特定されるコンポーネントごとに <nestedRef> ターゲッターを使用する個別のステップが存在するかのように、ステップが意味的に展開されます。ステップは同時にではなく連続的に実行され、ステップの順序はステップ型に応じて変化します。コンポーネントの 1 つに対してステップを実行しエラーが生じる場合は、そのステップは一致するほかのコンポーネントに対しては実行されません。

<call> または <addSnapshot> ステップのターゲッターとして使用される場合、ターゲッターは当該コンポーネントによって現在インストールされている、入れ子になったすべてのコンポーネント参照を照合します。コンポーネントの照合はインストール順に行われます。

<uninstall> ステップのターゲッターとして使用される場合、ターゲッターは当該コンポーネントによって現在インストールされている、入れ子になったすべてのコンポーネント参照を照合します。コンポーネントの照合はインストールの逆順に行われます。

`<toplevelRef>` インストール済みコンポーネントターゲッター

<toplevelRef> 要素は、現在の複合コンポーネントによって宣言または継承が行われた最上位のコンポーネント参照を特定します。このターゲッターを使用できるのは、複合コンポーネント内のステップだけです。

<toplevelRef> 要素は、<checkDependency>、<createDependency>、<call>、<uninstall>、および <addSnapshot> ステップのターゲッターとして使用できます。

このターゲッターは、name、path、および version 属性が参照先コンポーネントに基づいて事前定義されることを除き、意味的に <installedComponent> ターゲッターと同じです。詳細は、「 <installedComponent> インストール済みコンポーネントターゲッター」を参照してください。

`<toplevelRef>` ターゲッターの属性

<toplevelRef> ターゲッターには次の属性があります。

name – identifier 型の必須属性で、当該コンポーネント内の最上位コンポーネント参照の名前。
versionOp – オプション属性で、参照先コンポーネントのバージョンをターゲットホスト上にインストールされたコンポーネントのバージョンと比較する際に使用する演算子を指定します。複数のインストール済みコンポーネントが適用される場合、最後にインストールされたコンポーネントが使用されます。

使用できる値は、=、>=、および > です。この属性を指定しないと、>= が使用されます。
onlyCompat – オプション属性で、照合されるコンポーネントを指定します。true の場合、参照先コンポーネントと呼び出し互換性のあるコンポーネントだけを照合する必要があることを示します。デフォルト値は false です。
installPath – オプション属性で、参照先コンポーネントのインストールパス。この属性を指定しないと、任意のパスの最新の参照先コンポーネントインストールが使用されます。この値は、コンポーネントの解決処理の前に共通書式に変換されます。この属性は、単純置換変数を参照できます。
host – オプション属性で、参照先コンポーネントがインストールされているホスト。デフォルトでは、host は現在のホストです。host 属性の詳細は、「<retarget> ステップの属性」を参照してください。この属性は、単純置換変数を参照できます。

`<dependee>` インストール済みコンポーネントターゲッター

<dependee> 要素は、呼び出し側コンポーネントによってその依存性 (<createDependency> で作成される) が宣言されたインストール済みコンポーネントを特定します。このターゲッターを使用できるのは、コンポーネント内のステップだけです。

<dependee> 要素は、<call>、<uninstall>、および <addSnapshot> ステップのターゲッターとして使用できます。

`<dependee>` ターゲッターの属性

<dependee> ターゲッターには identifier 型の 1 つの必須属性 name があり、これは当該コンポーネントによって作成される依存性の名前です。

`<allDependants>` インストール済みコンポーネントターゲッター

<allDependants> 要素は、呼び出し側コンポーネントに対して依存性 (<createDependency> で作成) を宣言してあるインストール済みコンポーネントのセットを特定します。このターゲッターを使用できるのは、コンポーネント内のステップだけです。

<allDependants> 要素は、<call>、<uninstall>、および <addSnapshot> ステップのターゲッターとして使用できます。

このターゲッターは、包含するステップを、一致するすべてのコンポーネントにマップさせるという点で <addNestedRefs> ターゲッターと似た機能を持ちます。依存コンポーネントに対するマップの順序は指定されません。

`<allDependants>` ターゲッターの属性

<allDependants> ターゲッターは、identifier 型の 1 つの必須属性 name を持っています。これはほかのコンポーネントによって当該コンポーネントに対して作成される依存性の名前です。

`<targetableComponent>` インストール済みコンポーネントターゲッター

<targetableComponent> 要素は、ホストを対象とする特定のコンポーネントと関連付けられた、ターゲット可能コンポーネントを特定します。

<targetableComponent> 要素は、<call>、<uninstall>、<checkDependency>、<createDependency>、および <addSnapshot> ステップのターゲッターとして使用できます。

`<targetableComponent>` ターゲッターの属性

<targetableComponent> ターゲッターには 1 つのオプション属性 name があり、これはホストを対象とするコンポーネントの名前です。この属性を指定しないと、値は現在のターゲットホストになります。この属性は、単純置換変数を参照できます。

共通イントールパスの書式

インストールパスはインストール済みコンポーネント参照内に指定できます。その場合、installPath 属性の値は、インストール済みコンポーネント参照を解釈処理する前に、共通書式に変換されます。このような変換が行われるのは、インストール済みコンポーネントのインストールパスが、共通書式でも保存されるためです。

共通書式では、インストールパス内にあるパス区切り文字はすべてスラッシュ「/」に置き換えられます。パス区切り文字は、Master Server で動作中のオペレーティングシステムに固有です。末尾の「/」は削除されます。ルートインストールパス (/) は例外で、空のパスには変換されません。

Master Server アプリケーションが UNIX ベースのシステムで実行中である場合、末尾のスラッシュは無視されます。そのため、/opt/apache ディレクトリにインストールされているコンポーネントを指すためには、/opt/apache/ と /opt/apache の両方を使用できます。

リポジトリコンポーネントターゲッター

この節では、Master Server リポジトリに包含ステップ (install など) の対象として存在する特定のコンポーネントを指定する要素を説明します。対象となるすべてのステップですべてのターゲッターを使用できるわけではありません。各ターゲッターは、それ自体が使用できるステップを指定します。