第 3 章 N1 Service Provisioning System Software プランのスキーマ

この章では、N1 Service Provisioning System software プランの XML スキーマについて説明します。

プロビジョニングソフトウェア の XML スキーマアーキテクチャーの概要は、第 1 章を参照してください。

executionPlan 要素

プラン全体は、<executionPlan> 要素によって包含されます。

以下の表の「構成可能」列は、個々の属性に置換変数参照が「:[varName]」という形式で含まれるかどうかを示します。

executionPlan 要素属性

executionPlan 子要素

プラン単純または複合のどちらかです。 単純プランはほかのプランを含まず、ほかのプランを呼び出すこともありません。 単純プランは、特定の対象マシンセットに対して実行される手順の連続リストです。 複合プランには、ほかのサブプランだけが入っています。 複合プランが再帰的に包含している各単純サブプランは、それぞれ異なる対象を持ちます。このため、複合プランは直接の対象とはなりません。

plan paramList 要素

plan <paramList> 要素は <executionPlan> 要素の子であり、プラン内の手順およびそれらの参照コンポーネントが使用する一連のパラメタを宣言するために使用されます。 このプランが最上位のプランとして実行される場合、呼び出し側はこのリストで宣言された全パラメタの値を入力するように求められます。 このプランがほかのプラン内で <execSubplan> 手順の結果として呼び出される場合、呼び出し側のプランは <paramList> で宣言されたすべての非デフォルトパラメタの値を明示的に渡す必要があります。

plan paramList 要素の子要素

plan param 子要素

plan <param> 要素は plan <paramList> 要素の子であり、プラン内で使用するパラメタの宣言に使用されます。

plan param 子要素属性

plan varList 要素

plan <varList> 要素は <executionPlan> および <inlineSubplan> 要素の子であり、プラン内の手順およびそれらが参照するコンポーネントによって使用される一連の変数を宣言するために使用されます。 これらの変数の値は宣言時に定義され、再定義は行えません。

plan varList 要素

plan var 子要素

plan <var> 要素は plan <varList> 要素の子であり、プラン変数 (名前や値など) を宣言するために使用されます。

plan var 子要素属性

simpleSteps 要素

<simpleSteps> 要素は <executionPlan> および <inlineSubplan> 要素の子であり、1 つ以上の「共通」手順または「単純プラン専用」手順から構成されます。 <simpleStep> 要素の存在は、そのプランが単純 (複合に相対する) プランであることを示します。 実行時にこの要素内の手順は、呼び出し側によって選択された一連の論理対象ホストで順次実行されます。

simpleSteps 要素属性

simpleSteps limitToHostSet 属性

<simpleSteps> 要素の limitToHostSet 属性は、当該プランの有効な対象と見なされるホストを含むホストセットの名前を指定します。 この属性を指定しないと、すべてのホストが有効な対象と見なされます。 すべてのホストを有効な対象としない場合、クライアントが指定する対象はこの要素で指定されるホストセットに含まれるホストのサブセットでなければなりません。 指定されたホストセットに含まれないホストが対象内に存在する場合、その状況はプラン実行時エラーです。 既存のホストセットに一致しない名前を指定するのも、プラン実行時エラーです。 ここで説明するプラン実行時エラーは、プリフライトが始まる前に検証の段階で報告されます。

simpleSteps 要素の子要素

<simpleSteps> 要素の子は、1 つ以上の「共通」手順または「単純プラン専用」手順から構成されます。 これらの手順には、プランパラメタおよびプラン変数の参照を含めることができます。

詳細は、「単純プラン専用手順」を参照してください。

compositeSteps 要素

<compositeSteps> 要素は <executionPlan> および <inlineSubplan> 要素の子であり、1 つ以上の「複合プラン専用」手順から構成されます。 <compositeStep> 要素の存在は、そのプランが複合 (単純に相対する) プランであることを示します。 <compositeSteps> 要素に属性は含まれません。

compositeSteps 要素の子要素

<compositeSteps> 要素の子は、1 つ以上の「複合プラン専用」手順から構成されます。 これらの手順には、プランパラメタおよびプラン変数の参照を含めることができます。

詳細は、「単純プラン専用手順」を参照してください。

compositeSteps 要素の子要素

<compositeSteps> 要素の子は、1 つ以上の「複合プラン専用手順」手順から構成されます。 これらの手順には、プランパラメタおよびプラン変数の参照を含めることができます。

「単純プラン専用手順」を参照してください。

共通手順

この節では、コンポーネントまたは単純プランのどちらでも使用できる手順を示します。 該当する手順は次のとおりです。

• <call> (「call 手順」 で説明)

• <checkDependency> (「CheckDependency 手順」 で説明)

• <execJava> (「execJava 手順」 で説明)

• <execNative> (「execNative 手順」 で説明)

• <if> (「if 手順」 で説明)

• <pause> (「pause 手順」 で説明)

• <processTest> (「processTest Step」 で説明)

• <raise> (「raise 手順」で説明)

• <reboot> (「reboot 手順」 で説明)

• <retarget> (「retarget 手順」 で説明)

• <sendCustomEvent> (「sendCustomEvent 手順」 で説明)

• <transform> (「transform 手順」 で説明)

• <try> (「try 手順」 で説明)

• <urlTest> (「urlTest 手順」 で説明)

以下の表の「構成可能」列は、個々の属性に置換変数参照が「:[varName]」という形式で含まれるかどうかを示します。

call 手順

<call> 手順は、対象ホスト上にインストールされたコンポーネントに関連付けられた制御プロックの実行に使用できます。

call 手順属性

call 手順の子要素

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 手順の子要素

execJava 手順

対象ホスト上で Java^TM Executor インスタンスを実行するために使用する手順です。 Executor インスタンスが例外を送出する場合、手順は失敗し、実行が停止します。

<execJava> 手順は、内部使用だけを意図した高度な機能です。

execJava 手順属性

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

execJava 子要素

execNative 手順

<execNative> 手順は、対象ホストでネイティブコマンドを実行するために使用されます。 コマンドが予期しなかった結果を生成する場合、手順は失敗し、実行が停止します。

execNative 手順属性

execNative は、次のものを指定するために入れ子になった要素を持つことができます。

• 環境変数

• バックグラウンド実行

• コマンドの標準出力ファイル

• コマンドエラーの出力ファイル

• コマンド入力

• 実行するコマンド

• 手順の成功基準

execNative 要素の子要素

1 <background> 要素を指定する場合は、<outputFile> と <errorFile> の両方を指定する必要があります。

2 inputText および inputFile 要素は省略可能です。 これらの指定は一度に 1 つずつ行う必要があります。

3 exec または shell 要素の 1 つを指定する必要があります。 execNative 要素内に exec 要素と shell 要素の両方を入れることは認められません。

<inputText> および <inputFile> 要素は省略可能です。 これらの指定は一度に 1 つずつ行う必要があります。

3 exec または shell 要素の 1 つを指定する必要があります。 execNative 要素内に exec 要素と shell 要素の両方を入れることは認められません。

env 子要素

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

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

env 要素属性

background 要素

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

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

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

• 実行されるコマンドの標準出力およびエラー出力はキャプチャされません。 「details」をクリックすると、終了ステータス 0 と、空の出力、およびエラー出力が表示されます。 しかし、バックグラウンドでネイティブコマンドを開始するのに問題があった場合は、エラーの特性と診断出力に応じ、別の終了ステータスが表示されます。

• <outputFile> および <errorFile> 要素を指定する必要があります。 指定したファイルがすでに存在する場合、それらは無効にされます。

outputFile 要素

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

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

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

outputFile 属性

errorFile 要素

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

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

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

errorFile 属性

inputText 子要素

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

<inputText> は、CDATA セクションの入力を囲む目的で使用できます。入力を囲むことで、入力フォーマットを保持するとともに、文字 `& や `<' を含む入力で発生しえる解析エラーを防ぐことができます。

(例:

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

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

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

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

inputFile 子要素

<inputFile> 要素は、<execNative> の子要素です。 <inputFile> 要素は、実行されるコマンドの標準入力に送り込まれるコンテンツが入った、遠隔リモートエージェント上のローカルファイルのパスを指定するために使用されます。 ローカルファイルのパスは、<inputFile> 要素内の name 属性を使用して指定します。

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

inputFile 要素属性

exec 子要素

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

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

• 属性 cmd: 実行するコマンドの名前を指定する

• 入れ子になった一連の arg 要素: cmd で指定されるコマンドの各引数を指定する

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

次に、<execNative> 手順の例を示します。

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

この手順は、コマンド ps –fu sps を実行します。

exec 要素属性

exec 要素の子要素

arg 子要素属性

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> 

このコードは次のコマンドを実行します。

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

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

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

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

シェル要素の属性

successCriteria 要素

<successCriteria> 要素は、<execNative> の子要素です。 <successCriteria> 要素は、<execNative> 手順が正常に実行されたかを評価するために使用される基準を指定します。 この要素が指定されない場合のデフォルト値は次のとおりです。

<successCriteria status=”0”/> 

空の successCriteria を指定すると、successCriteria は無視されます。 次のタグを指定した場合には、

<successCriteria/> 

コマンドがどのような出力または終了コードを生成した場合でも、手順は常に成功します。

successCriteria 要素属性

inverse 属性を true に設定すると、<successCriteria> 内で指定された各条件は無視されます。

たとえば、次の successCriteria を持つ <execNative> 手順の場合、

<successCriteria status=”1” outputMatches=”bin” errorMatches=”none” inverse=”true”/> 

ステータスが 1 でなく、出力が `bin' に一致せず、エラーが `none' に一致しない場合だけ成功します。

inverse 属性だけを含む <successCriteria> 要素は、inverse 属性なしで保存されます。 つまり、次のように指定すると、

<successCriteria inverse=”true”/> 

次のように保存されます。

<successCriteria/> 

結果的に、<successCriteria> は無視されます。

if 手順

手順ブロックを条件付きで実行するために使用される手順です。 この手順に属性はなく、子は <condition>、<then>、および <else> 要素から構成されます。

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

if 手順の子要素

if 手順の例

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

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

condition 要素

<if> 手順の子要素であり、ブール式を指定します。 この要素に属性はありません。この要素は、ブール演算子の子要素を 1 つだけ含む必要があります。 許可されるブール演算子の詳細は、ブール演算子の節を参照してください。

then 要素

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

else 要素

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

pause 手順

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

pause 手順属性

processTest Step

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

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

processTest 手順属性

raise 手順

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

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

raise 手順属性

raise 手順の例

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

<control blockName="default">
	<try>
		<block>
			<!-- some arbitrary processing here -->
		</block>
		<catch>
			<!-- note error in log -->
			<execNative>
				<exec cmd="appendLog"> <arg value="an error occurred"/> </exec>
			</execNative>
			<!-- rethrow error -->
			<raise/>
		</catch>
	</try>
</control> 

reboot 手順

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

reboot 手順属性

retarget 手順

一連の手順の実行対象を変更する手順。 retarget 手順は入れ子にすることができます。

retarget 手順属性

retarget 手順の子要素

retarget 手順の host 属性

host 属性は、各種のコンポーネントターゲッター要素内のほか、<retarget> 手順内でも使用できます。 この属性の値はホストの名前であり、置換変数参照を含むことができます。 また、シンボリック名「/」を含めて現在の実行対象のルート物理ホストを参照することも、あるいは「..(/..)*」を含めて現在の実行対象の親ホストを参照することもできます。 サポートされている全構文は、第 16 章の「ホストの切り替え」に示されています。

host 属性をコンポーネントターゲッター内に指定することは、包含する手順を retarget 手順内に含めることに意味的に同じです。

retarget 手順の実行意味論

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

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

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

2. 現在のユーザーがそのホストにおいて「プランの実行」アクセス権を所有しているかを検証します。 所有していない場合、エラーが発生します。

3. このホストのルート物理ホストに RA が含まれていること、ルート物理ホストに接続可能なこと、およびルート物理ホストが最新の状態で準備が整っていることを確認します。 この条件が満たされない場合、エラーが発生します。

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

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

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

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

空の <retarget> ブロックは、現在のユーザーが適切なアクセス権を持っているかということと、ホストの準備が適切に行われているかということをあらかじめ検証するメカニズムとして依然として有用です。

retarget 手順の例

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

「adminHostName」変数は、呼び出し側の現ホスト (これは管理対象サーバーを含んでいる vhost と見なされる) で評価されます。 domainName 変数は、新しい対象ホスト (これは管理サーバーを含んでいる vhost と見なされる) で評価されます。 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 手順属性

transform 手順

<transform> 手順は、対象ホスト上に含まれるファイルのテキストベース変換を行うために使用されます。 現時点では、Perl5 および XSLT ベースの変換がサポートされています。

transform 手順属性

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

transform 要素の子要素

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

• 入力ソースに適用する XSLT 変換を定義する単一の <stylesheet> 要素

• 入力ソースに順次適用する Perl5 ベースの置換パターンを定義する 1 つ以上の <subst> 要素

• 変換を含んでいる外部ファイルを指定する単一の <source> 要素

• 空。これは、入力ファイルのコンテンツが出力ファイルに直接コピーされることを意味します。 これは、zip アーカイブから抽出する場合または zip アーカイブに書き込む場合に便利です。

stylesheet transform 子要素

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

<stylesheet> 要素は、ネームスペース//www.w3.org/1999/XSL/Transform” で定義されているように XSLT バージョン 1.0 要素です。 詳細は、"http://www.w3.org/TR/xslt” に挙げられた XSLT 仕様を参照してください。 transform 要素の子として受け入れられるのは、XSLT <stylesheet> 要素だけです。 XSLT 仕様の節 2.3 で説明された XSLT シノニム <transform>、単純化された XSLT 変換構文とも、transform 要素の子としてはサポートされません。

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

<stylesheet> 要素が変換として使用される場合、入力ファイルが XML 形式で記述されていると見なされます。

stylesheet 要素の例

以下に、XSLT 変換の例を示します。

<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 transform 子要素

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

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

サポートされる構文の詳細は、Oro ドキュメント (class org.apache.oro.text.regex.Perl5Substitution) に入っています。

subst 要素属性

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 transform 子要素

<source> 要素は <transform> 手順の子であり、入力ファイルに適用する変換が入っている、対象ホスト上の外部ファイルを指定します。 各 <transform> 要素の子として指定できるのは <source> 要素 1 つであり、ほかの子要素と併用はできません。

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

source 要素属性

source 要素の type 属性

<source> 要素の「type」属性は、指定されたファイル内に含まれる変換の型を指定します。

値「PERL」は、<subst> 要素による変換に似た Perl5 ベースの変換を示します。 この場合、指定されるファイルは以下のような形式をとる必要があります。

<?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 仕様の節 2.3 で説明しているように任意の有効な最上位 XSLT 変換要素 (<stylesheet>、<transform>、単純化された XSLT 構文など) を含むことができます。

try 手順

<try> 手順は、手順ブロックの典型的なエラー処理とクリーンアップロジックを指定するために使用されます。 この手順に属性はなく、子は <block>、<catch>、および <finally> 要素から構成されます。

<try> 手順は次のように実行されます。

• <block> 要素内の手順は、すべてが完了するか (Plan Executor の各手順に関する エラー定義に従って) 手順のどれかが失敗するまで順に実行されます。

• <catch> 要素が定義されており、かつプランの中断 (abort) またはプランのタイムアウト以外の手順エラーでブロック要素の実行が終了した場合にかぎって、すべてが完了するかあるいは手順のどれかが失敗するまで <catch> 要素内の手順が順に実行されます。

• <finally> 要素が定義されている場合、その手順はそれらがすべてが完了するか手順のどれかが失敗するまで順に実行されます。 これは、プランの中断またはプランのタイムアウトのために先の 2 つの要素のどちらか一方が停止しないかぎり、それらの要素の成否に関係なく発生します。

• 上記の規則があることから、プランの中断またはプラン (手順ではなく) のタイムアウトのために包含される手順のどれかが失敗する場合、包含されるほかの手順は実行されず、<try> 手順の実行はエラーを示して終了します。

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

<try> 手順は、以下のように成否が決まります。

• <try> 手順に <finally> 要素だけが含まれる場合 (<catch> は含まれない)、<block> または <finally> 要素の実行が失敗するとこの手順は失敗します。

• <try> 手順に <catch> 要素だけが含まれる場合 (<finally> は含まれない)、この手順は以下の状況のどちらか一方が発生するときだけ失敗します。

  • <catch> 要素の実行が行われて失敗した

  • プランの中断またはプランのタイムアウトのために <block> 要素が失敗した

• <try> 手順に <catch> および <finally> 要素の両方が含まれる場合、この手順は以下の状況のいずれかが発生するときだけ失敗します。

  • <catch> または <finally> 要素が実行されて失敗した

  • <finally> 要素が実行されて失敗した

  • プランの中断またはプランのタイムアウトのために <block> 要素が失敗した

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

try 手順の子要素

try 手順の例

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

<installSteps blockName="default">
	<deployResource/>
	<try>
		<block>
			<call blockName="restart"><thisComponent/></call>
		</block>
		<catch/><!-- suppress all typical errors -->  
	</try>
</installSteps> 

try ブロックは、インテリジェントな自動アップグレードをモデル化するためにも使用できます。 バージョン 1.1 のコンポーネントが存在し、バージョン 1.0 を以前にインストールしたことがあるかどうかに基づいて選択できる 2 つの異なるインストールルーチン、フレッシュインストールとアップグレードインストールが存在する場合を考えてみます。 このケースは、以下のように単一のインストールブロックとしてモデル化できます。

<installSteps blockName="default">
	<try>
		<block>
			<checkDependency>
				<installedComponent name="foo" version="1.0"/>
			</checkDependency>
			<!-- 1.0 install exists, do upgrade -->
		</block>
		<catch>
			<!-- 1.0 install doesn"t exist, do fresh install -->
		</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>
			<!-- process file in some way -->
		</block>
		<finally>
			<execNative>
				<exec cmd="rm"><arg value=":[file]"/></exec>
			</execNative>
		</finally>
	</try>
</control> 

block 要素

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

catch 要素

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

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

finally 要素

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

<finally> 要素は、ほかの典型的なエラー状況を考慮することなくクリーンアップを開始する必要がある場合に、主にリソースのクリーンアップと解放を行う手順を指定する目的で使用されます。

urlTest 手順

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

urlTest 手順の属性

複合プラン専用の手順

この節では、複合プラン内でだけ使用できる手順を示します。 プラン内に含まれる手順は、プラン変数およびプランパラメタの参照を含むことができます。

execSubplan 手順

<execSubplan> 手順は、ほかのプランを実行するために使用される手順です。 <execSubplan> 手順は、compositeSteps> 要素の子としてしか指定できません。

execSubplan 手順属性

execSubplan 手順の子要素

inlineSubplan 手順

<inlineSubplan> 手順は、連続した複数の手順を実行するために使用される手順です。 この手順は、<compositeSteps> 要素の子としてしか指定できません。

<inlineSubplan> 手順は <execSubplan> 手順に類似していますが、<execSubplan> 手順は実行する外部プランの名前を指定するのに対し、<inlineSubplan> 手順は子要素として実行するプランを直接包含します。 インラインサブプランと最上位プランの一番の違いは、インラインサブプランは別個の名前付きエンティティとして保存されず、<execSubplan> 手順によって外部から参照が行えないのに対し、最上位プランは別個の名前付きエンティティであり、<execSubplan> 手順からの参照が可能であることです。 インラインサブプランは、サブプランコンテンツが簡潔で呼び出し側プランのコンテキストとロジックに直接結合されている場合に便利です。このような場合以外は、スタンドアロンプランとして使用しても無意味です。 これらのケースでは、自己包含した 1 つのユニットに全手順を含めるとメンテナンスが容易になるほか、プランを読みやすくなります。

最上位プランと異なり、インラインサブプランはパラメタを宣言することはできません。 インラインサブプランは、包含するすべてのプランのパラメタと変数を暗黙に継承します。 インラインサブプランがそれ自身にローカルな変数を別途宣言することは可能であり、これにより包含するプランの変数とパラメタを隠蔽できます。 サブプラン変数と包含するプランの変数が同じ名前を持つと、サブプラン変数が包含するプランの変数を隠蔽します。 このようなケースでは、その手順で使用できるのは一番内側のサブプランによって宣言された変数の値だけです。

inlineSubplan 手順属性

inlineSubplan 要素の子要素

<inlineSubplan> 要素は、オプションの <varList> と、それに続く追加子要素 1 つで構成されます。この子要素は、インラインサブプランが単純プランであるか複合プランであるかに基づき、<simpleSteps> または <compositeSteps> です。

単純プラン専用手順

この節では、単純プラン内でだけ使用できる手順を示します。

プラン内に含まれる手順は、そのプランによって宣言された変数のほか、すべての包含プランの隠蔽されていないあらゆる変数とパラメタを参照できます。

install 手順

<installStep> は、コンポーネントのリソースを対象ホストにインストールするために使用される手順です。 これにより、関連付けられたコンポーネントの指定された <installSteps> 要素の手順が実行されます。 この手順は、<simpleSteps> 要素の子としてしか指定できません。

install 手順属性

install 手順の子要素

uninstall 手順

<uninstallStep> は、対象ホスト上に現在インストールされているコンポーネントのリソースをアンインストールするために使用される手順です。 これにより、関連付けられたコンポーネントの指定された <uninstallSteps> 要素の手順が実行されます。 この手順は、<simpleSteps> 要素の子としてしか指定できません。

uninstall 手順属性

uninstall 手順の子要素