test

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

共有ステップ

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

<assign> ステップ

<assign> ステップは、以前に宣言した変数に値を再割り当てするために使用します。コンポーネントまたは単純実行プランで使用できる共有ステップです。割り当てられる変数が、プランまたはコンポーネントのローカルスコープで定義済みでない場合は、チェックイン時エラーになります。

<assign> ステップの属性

<assign> 要素には、2 つの必須属性があります。

<call> ステップ

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

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

<call> ステップの属性

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

<argList> 要素

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

呼び出されるサービスの方は、待ち受ける変数を <paramList> 要素を使用して宣言します。<argList> 内の変数と呼び出される <paramList> 内の変数は同じである必要はありません。

<paramList> 内で宣言される各変数のうちデフォルト値を持たないものについては、<argList> 内に同じ名前の対応する変数が含まれる必要があります。この条件が満たされない場合、プラン実行時にプリフライトエラーが発生します。プロビジョニングシステムは、 (<argList> 内に対応する変数が存在する) 呼び出される <paramList> で各変数を実行します。呼び出されるサービスの実行中に、<paramList> 内の変数の値は、<argList> 内の対応する変数の値を取得します。

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

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


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

<argList> 要素の属性

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

<checkDependency> ステップ

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

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

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

<execJava> ステップ

<execJava> ステップは、ターゲットホストの JavaTM Executor インスタンスを実行します。Executor インスタンスが例外を送出する場合、ステップは失敗し、実行が停止します。

<execJava> ステップには、次のオプションの子要素があります。

<execJava> ステップの属性

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

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

execJava assign* 子要素

<assign*> 要素のセマンティクスは、<assign> ステップのものに似ています。<assignOutput> 要素と <assignError> 要素に同じ変数名が指定されると、チェックインエラーがトリガーされます。出力およびエラーストリームは、構成ファイルで pe.maxOutputSnapshotBytes の値を指定することにより、データベース出力を現在切り捨てている方法とまったく同じ方法で切り捨てます。

<assign*> 要素の varName で示される変数が、プラン内、コンポーネントのローカルスコープ内、またはプランのローカルスコープ内に存在しない場合、チェックインエラーになります。

<execNative> ステップ

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

<execNative> ステップには、次の入れ子の子要素を含めることができます。

<execNative> ステップの属性

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

<env> 要素

<execNative> 要素には、コマンドの環境変数を指定する <env> 要素をオプションで含められます。<env> を使用すると、コマンドの環境に新しい変数を用意したり、既存の変数をオーバーライドできます。

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

<env> 要素の属性

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

<background> 要素

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

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

<outputFile> 要素

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

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

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

<outputFile> 要素属性

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

<errorFile> 要素

<errorFile> 要素は <execNative> 要素の子要素です。<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> 要素の子要素です。この子要素は、実行されるコマンドの標準入力として使用される内容が入った、リモートエージェント上のローカルファイルのパスを指定します。ローカルファイルのパスは、<inputFile> 要素の name 属性を使用して指定します。

注 –

<inputFile> 要素は、<execNative> コマンド内で <inputText> 要素と同時に使用できません。

<inputFile> 要素属性

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

<exec> 要素

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

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

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

<shell> 要素

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

次の <execNative> の例は、 /usr/bin/bash -c `ls -l | fgrep `*test*' | sort -u > file.out' コマンドを実行します。


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

書式を保持するとともに 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 (論理積) がとられます。

<if> ステップ

このステップは、ステップブロックを条件付きで実行するために使用されます。このステップには属性がありません。子要素は <condition>、 <then>、および <else> です。<condition> および <then> 要素は、1 回出現する必要があります。<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> 要素は positiveInteger 型の 1 つの必須属性 delaySecs を持ちます。この属性は待機する秒数です。

<processTest> ステップ

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

注 –

<processTest> ステップは UNIX® システムにのみ適用されます。

<processTest> ステップの属性

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

<raise> ステップ

<raise> ステップは、常に失敗するステップです (<try> ステップによる捕捉と処理は可能)。「<try> ステップ」を参照してください。

<raise> ステップは、人為的なステップを構築することなくエラー状況を示す手段として使用されます。このステップの出現がもっとも多いのは <catch> ブロック内であり、クリーンアップ後のエラー状況を伝えるために使用されます。「<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 以外のプラットフォームで検出された場合は、エラーが発生します。マスターサーバーと同じホスト上に存在するエージェントをリブートした場合もエラーとなります。ここで説明しているエラーはプリフライトエラーです。

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

<retarget> ステップ

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

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

<retarget> ステップの属性

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

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

注 –

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

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

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

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

  1. ホスト名を実際のホストに解決します。そのようなホストが存在しない場合、エラーが発生します。

  2. プランのフォルダ、またはこのステップを含むコンポーネントに関して、現在のユーザーが、そのホストにおいて「実行」アクセス権を所有しているかを検証します。所有していない場合、エラーが発生します。

  3. ホストのルート物理ホストに関して、以下の条件が満たされていることを検証します。

    • リモートエージェントが含まれている。

    • ルート物理ホストに接続できる。

    • ルート物理ホストが最新の状態で準備が整っている。

    これらの条件が満たされない場合、エラーが発生します。

  4. 以前にアクセスしたすべてのホストでロックを保持したまま、このホストでロックを取得します。現在の実行スレッドがすでにホストをロックしている場合、この処理は事実上ノーオペレーション (空命令) となります。ホストがすでにほかの実行スレッドによってロックされている場合、この処理はホストのロックが解除されるまでブロックします。ロック要求のためにデッドロックが起きた場合は、エラーが発生します。

  5. そのホストが再設定され、新しい「現」ホストになります。「物理」ホストは、新しい「現」ホストに基づいて再設定されます。「初期」ホストは変化しません。

上記のステップが完了したあとで、<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>

<return> ステップ

<return> ステップ要素を使用すると、現在のブロックの実行を停止し、オプションとして returns 値を呼び出し側ステップに返すことができます。<return> ステップ要素は、次の要素内だけに出現できます。

install、uninstall、または call ブロック宣言内に returns=true 属性が存在する場合は、ブロック定義の実行パスごとに、対応する捕捉されていない <raise> または <return> ステップが必須になります。

<return> ステップはブロック内の任意の場所に出現でき、通常は Java return 文のセマンティクスの後に続きます。ブロックの複雑さによっては、すべての実行パスが確実に値を返すように、2 つ以上の <return> ステップが必要になります。return に続いて追加ステップが示される場合は、チェックインエラーがスローされます。ただし、<return> ステップが <try> ブロック内に出現し、追加ステップが対応する <finally> ブロックで囲まれている場合を除きます。<raise> ステップが捕捉されておらず、現在のブロックスコープ内で処理される場合に限り、実行パスが <raise> ステップで終了することもあります。ブロックで returns 属性が指定されていなくても <return> ステップをブロック内で使用できますが、その場合は返す値を指定してはいけません。<return> ステップで値が指定されていても、returns 属性がそのブロックに指定されていないと、チェックインエラーが発生します。

<return> ステップの属性

<return> ステップには、String 型の属性値が 1 つあります。この値は戻り値です。値が指定されていない場合、ブロックは値が返されずにステップ実行されます。

例 2–4 <try> および <finally> ブロックでの <return> ステップの使用

次の例は、<try> および <finally> ブロック内の <return> ステップを示しています。値 b が返されます (Java の場合と同様)。


<try>
    <block>
        <return value="a"
    </block>
    <catch/>
    <finally>
         <return value="b">
    </finally>
</try>
例 2–5 条件付きでの <return> ステップの使用

条件付きで使用される <return> ステップの例を、次に示します (分かりやすいよう行番号を追加)。var1 が true の場合、5 行目の <return> ステップによってブロックの残りのブロックがスキップされます。8 行目と 9 行目はまったく実行されません。var1 が true ではない場合は、9 行目の <return> ステップが、ブロック内で実行される最後のステップになります。


1. <control name = "blah" returns="true">
2.   <varList>
3.   <var name="var1" default="val1"/>
4.   <var name="var2" default="val2"/>
5.   </varList>
6.   <if>
7.      <condition><istrue value=":[var1]"/></condition>
8.      <then>
9.         <return value=":[var2]">
10.     </then>
11.  </if>
12.  <assign varName="var2" value="new value"/>
13.  <return value=":[var2]"/>
14.</control>
例 2–6 <try> ブロック内での条件付きの <return> ステップの使用

一方、次の例は、<try> ブロック内での <return> ステップの条件付きの使用を示しています。var1 が true かどうかにかかわらず、15 行目が実行される最後の行になります。


1. <control name="blah" returns="true">
2.   <varList>
3.   <var name="var1" default="val1"/>
4.   <var name="var2" default="val2"/>
5.   </varList>
6.   <try>
7.      <block>
8.          <if>
9.              <condition><istrue value=":[var1]"/></condition>
10.             <then>
11.                 <return value=":[var2]">
12.             </then>
13.         </if>
14.         <assign varName="var2" value="new value"/>
15.         <return value=":[var2]"/>
16.     </block>
17.  <catch/>
18.  <finally>
19.      <pause delaySecs="5"/>
20.  </finally>
21.   </try>
22.</control>
例 2–7 inlineSubplan 内での <return> ステップの使用

次の例は、inlineSubplan または execSubplan 本体の <SimpleSteps> 内にある <return> ステップを示しています。制御は、inlineSubplan または execSubplan を呼び出す一連のステップ内の次の行に戻ります。4 行目の <return> ステップのあとの、次のステップは 7 行目です。


1. <complexSteps>
2.   <inlineSubplan>
3.       <simpleSteps>
4.           <return/>
5.       </simpleSteps>
6.   </inlineSubplan>
7.   <inlineSubplan>
8.       <simpleSteps>
9.            <pause delaySecs="1"/>
10.      </simpleSteps>
11.  </inlineSubplan>
12.</complexSteps>

<sendCustomEvent> ステップ

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

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

<transform> ステップ

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

変換の前にターゲットホスト上に出力ファイルが存在している場合、ファイルのアクセス許可と所有権は保存されます。ただし、出力ファイルが新しいファイルである場合、デフォルトの RA のアクセス許可を継承します。

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

<transform> ステップの属性

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

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–8 <stylesheet> 要素の使用法

以下の変換では、/etc/hosts ファイル内で各 a が b に変更されます。これらの変更で hosts ファイルが上書きされます。


<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> 要素には次の属性があります。

例 2–9 <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> 要素には次の属性があります。

<try> ステップ

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

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

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

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

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

<block> 要素の失敗は <catch> 要素の存在で抑制されます。

<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–10 <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> ステップには次の属性があります。