<snapshot> 要素

<snapshot> 要素は <snapshotList> 要素の子要素で、このコンポーネントのインストール状態をキャプチャーするために実行される一連のステップを定義します。<createSnapshot> または <addSnapshot> ステップでこの snapshot ブロックの名前が指定されると、prepare ブロック内のステップが順に実行されます。続いて capture ブロックで指定されたファイルターゲットサーバーのキャプチャー領域でキャプチャーされ、最後に cleanup ブロック内のステップが順に実行されます。

スナップショットブロックは、コンポーネントの現在の状態をそのインストール時の状態と比較するためにも使用されます。具体的には、ターゲットサーバーで prepare ステップが再実行され、続いてインストール時にキャプチャーされたファイルが現在のファイル状態と比較され、cleanup ステップが再実行されます。

<snapshot> 要素には次の子要素があります。

• <paramList> – オプション要素で、この snapshot の prepare、capture、および cleanup ブロックで使用されるパラメータのリストです。この要素は 1 回しか出現できません。

• <varList> – オプション要素で、この snapshot の prepare、capture、および cleanup ブロックで使用されるローカル変数のリストです。この要素は 1 回しか出現できません。

• <prepare> – オプション要素で、ファイルのキャプチャーまたは比較に備えて実行されるステップを含みます。この要素は 1 回しか出現できません。

• <capture> – オプション要素で、この snapshot の中でキャプチャーされるファイルとディレクトリのリストを含みます。この要素は 1 回しか出現できません。

• <cleanup> – オプション要素で、キャプチャーまたは比較の完了後に実行されるステップを含みます。この要素は 1 回しか出現できません。

このスナップショットが <createSnapshot> ステップから呼び出される場合は、必要なパラメータをその <paramList> 要素で宣言することはできません。

<varList>、<prepare>、<capture>、および <cleanup> 要素は、集合的にスナップショットの本体を定義します。スナップショットブロックが抽象と宣言される場合、本体は含められません。

デフォルトでは、派生コンポーネントはそのベースコンポーネントの、アクセス可能なすべてのスナップショットブロックを継承します。スナップショットブロックをオーバーライドするセマンティクスは、インストールブロックをオーバーライドするセマンティクスと同じです。

派生コンポーネントスナップショットブロックの prepare ブロックからベースコンポーネントスナップショットブロックの prepare ブロックを呼び出す方法はありません。同じことが cleanup についても言えます。この種の呼び出しを行うには、ベースコンポーネントがその <prepare> および <cleanup> ステップを、派生コンポーネントから呼び出し可能な制御ブロックに分解する必要があります。

<snapshot> 要素の属性

この要素には次の属性があります。

• access – accessEnum 型のオプション属性で、スナップショットブロックのアクセシビリティーを指定します。次の値が使用できます。

  • PUBLIC – アクセスは制限されません。これがデフォルトです。

  • PROTECTED– アクセスは同じパス内の派生コンポーネントとエンティティーに制限されます。

  • PATH – アクセスは同じパス内のエンティティーに制限されます。

  • PRIVATE – アクセスはこのコンポーネントに制限されます。

• modifier – modifierEnum 型のオプション属性で、スナップショットブロックのオーバーライド要件を指定します。次の値が使用できます。

  • ABSTRACT – ブロックに本体を含めることはできません。 本体は、非抽象派生コンポーネントによって指定する必要があるためです。スナップショットブロックを抽象と宣言できるのは、コンポーネントも抽象と宣言されている場合だけです。抽象ブロックは専用にはできません。非抽象ブロックの場合、本体を宣言する必要があります。

  • FINAL – スナップショットブロックを派生コンポーネントによってオーバーライドすることはできません。

  この属性を指定しない場合、派生コンポーネントはブロックをオーバーライドするかどうかを選択できます。

• name – entityName 型の必須属性で、スナップショットブロックの名前です。この名前は、包含している <snapshotList> 内のすべてのスナップショットブロックの中で一意である必要があります。

• description – オプション属性で、スナップショットブロックを説明する文字列。この属性は文書化に便利です。

<prepare> 要素

<prepare> 要素は <snapshot> 要素の子要素で、ファイルのキャプチャーまたは比較に備えた一連のステップを定義します。これらのステップは、このスナップショットを対象とする <createSnapshot> または <addSnapshot> ステップと、このスナップショットを対象として実行される比較の両方の結果として実行されます。どのような場合も、これらのステップはファイルのキャプチャーまたは比較作業に先立って実行されます。

<prepare> 要素の子は、1 つ以上の <call>、<execNative>、および <transform> ステップから構成されます。ほかのステップは許可されません。包含されるステップは、スナップショットブロックで宣言されたローカルパラメータおよびローカル変数と、隠蔽されていない component 置換変数を参照できます。

<capture> 要素

<capture> 要素は、このスナップショットの一部としてキャプチャーされるファイルとリソースを定義します。キャプチャーは、<prepare> ブロック内のステップが実行されたあとでしか行われません。キャプチャーが完了すると、<cleanup> ブロック内のステップが実行されます。

<capture> 要素の子は、1 つ以上の <addFile>、<addSnapshot>、および <addResource> 要素から構成されます。このブロックに挙げられるファイルとディレクトリは、指定された順にキャプチャーされます。包含される子は、スナップショットブロックで宣言されたローカルパラメータおよびローカル変数と、隠蔽されていない component 置換変数を参照できます。

<addFile> 要素

<addFile> 要素は <capture> 要素の子要素であり、包含するスナップショットの一部としてキャプチャーされるファイルを指定します。

<addFile> 要素の属性

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

• path – 必須属性で、ターゲットホストのファイルシステム上のファイルまたはディレクトリのパス名を指定します。この属性は、単純置換変数を参照できます。

• ownership – オプション属性で、キャプチャーされたファイルの所有権オプションを指定します。

  スナップショットによってキャプチャーされるインストール状態の情報の 1 つに、ファイルおよびディレクトリの所有権があります。この所有権は UNIX のアクセス許可と同じではありません。所有権は、参照カウントの概念により近いと言えます。具体的には、ファイルまたはディレクトリは、1 つ以上のスナップショットによって所有されているものとしてキャプチャーできます。

  ほかのコンポーネントのインストールにより、ファイルの所有者が変更された場合、そのファイルがその初期状態と比較されたときに、この変更が認識され報告されます。この機能により、あるコンポーネントが、別のコンポーネントに関連付けられているファイルを誤って上書きしたために生じた差異を追跡することができます。スナップショットの所有権情報は、所有者テーブルと呼ばれる、ターゲットホスト上のリポジトリ内にキャプチャーされます。

  ownership 属性の値は以下のセマンティクスを持ちます。

  • SET_SELF – ownership 値がこの値に設定された場合、所有者テーブルは関連付けられたファイルまたはディレクトリ用の単一のエントリを含むように更新されます。そのエントリは、実行するインストール済みコンポーネントとスナップショットを所有者としてリストします。また、キャプチャーされたファイルの内容またはディレクトリの内容のキャプチャー領域 ID もリストします。

  • ADD_SELF – ownership がこの値に設定された場合、インストール済みコンポーネントとスナップショットが付加的な所有者として追加され、以前の所有者として既存のキャプチャー領域 ID を共有します。

  • ADD_TEMP – この値は ADD_SELF と似ていますが、新しいキャプチャーが常に作成されてその ID が常に新しいエントリに使用されます (ほかの所有者の ID を共有することはありません)。

  この属性を指定しない場合、デフォルト値は SET_SELF です。

• filter – boolean 型のオプション属性で、ファイルまたはディレクトリ、あるいはその両方をキャプチャーすべきかを示します。

  path の値がディレクトリである場合、この属性は、ディレクトリ自体、そのディレクトリに含まれるファイル、またはその両方をキャプチャーすべきかを示すために使用されます。path の値がディレクトリでない場合、この属性は無視され、ファイルが直接キャプチャーされます。この属性を指定しない場合、デフォルトの BOTH が使用されます。

  この属性の値には次のものがあります。

  • DIRECTORIES

  • FILES

  • BOTH

• recursive – オプション属性で、現在のフィルタ設定を使用してサブディレクトリを再帰的にキャプチャーすべきかどうかを示します。

  path の値がディレクトリである場合、この属性は、現在のフィルタ設定を使用してサブディレクトリを再帰的にキャプチャーすべきかどうかを示します。path の値がディレクトリでない場合、この属性は無視され、ファイルが直接キャプチャーされます。デフォルト値は true です。

• displayName – オプション属性で、このスナップショットエントリがほかのエントリと比較される際に表示に含めるテキスト。

  この属性は、単純置換変数を参照できます。

<addSnapshot> 要素

<addSnapshot> 要素は、外部スナップショットブロックを実行する必要があること、およびその内容をこのスナップショットに追加すべきであることを示します。

<addSnapshot> ステップを使用することは、次のシナリオのすべてと意味的に同じです。

• 呼び出されたスナップショットの <prepare> ステップを、呼び出し側スナップショットの prepare ブロックの最後に追加する

• 呼び出されたスナップショットの <cleanup> ステップを、呼び出し側スナップショットの cleanup ブロックの先頭に追加する

• 呼び出されたスナップショットの <capture> ステップを、(<addSnapshot> ステップの代わりに) 呼び出し側スナップショットの capture ブロックに追加する

呼び出される側および呼び出し側のスナップショットブロックによって参照されるファイルが重複しないように注意する必要があります。

<capture> 要素には、任意の数の <addSnapshot> ステップを含めることができます。呼び出される側のスナップショット自体には、その <capture> 要素内に任意の数の <addSnapshot> ステップを含められます。

<addSnapshot> コールアウトを使用してファイルをスナップショットに間接的に追加する場合、スナップショットのキャプチャーを開始した最上位のコンポーネントは (<addFile> 命令が入ったコンポーネントとは対照的に) ファイルの所有者と見なされます。同様に、スナップショットで比較が実行される場合、そのスナップショットで起動された最上位コンポーネントの <diff> 要素の <ignore> 指示だけが考慮されます。<addSnapshot> コールアウトの結果として出現したコンポーネントに含まれる <diff> 要素の <ignore> 指示は考慮されません。

<addSnapshot> 要素には、entityName 型の 1 つの必須要素 blockName があります。これは、実行する外部スナップショットブロックの名前です。

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

• <argList> – オプション要素で、スナップショットブロックに渡す引数の一覧。この要素は 1 回しか出現できません。

• <Installed component targeter> – オプション要素で、スナップショットブロックを含むコンポーネントを特定します。この要素を指定しない場合は、<thisComponent> が使用されます。

<addResource> 要素

<addResource> 要素は、包含するスナップショットの一部としてキャプチャーされるコンポーネントに関連付けられたリソースを指定します。この要素は、単純コンポーネントにしか含めることができません。

この要素は、次に示すように、同等の <addFile> 要素の簡略構文として機能します。

• 関連付けられたリソースが deployMode=ADD_TO のディレクトリリソースである場合、<addResource> は次の文と同義です。

  <addFile path="path-of-deployed-directory" filter="FILES" displayName="resourceSourcePath"/>

• 関連付けられたリソースが deployMode=REPLACE のディレクトリリソースである場合、<addResource> は次の文と同義です。

  <addFile path="path-of-deployed-directory" displayName="resourceSourcePath"/>

• これらのどちらでもない場合、関連付けられたリソースはファイルベースのリソースであり、<addResource> は次の文と同義です。

  <addFile path="path-of-deployed-file" displayName="resourceSourcePath"/>

<cleanup> 要素

<cleanup> 要素は <snapshot> 要素の子要素であり、ファイルのキャプチャーまたは比較が完了したあとで実行される一連のステップを定義します。これらのステップは、このスナップショットを対象とする <createSnapshot> または <addSnapshot> ステップと、このスナップショットを対象として実行される比較の両方の結果として実行されます。どのような場合も、これらのステップはすべてのファイルのキャプチャーまたは比較作業のあとに実行されます。cleanup ブロックは、prepare ブロックで作成された一時ファイルを削除するために使用します。

<cleanup> 要素の子は、1 つ以上の<call>、<execNative>、および <transform> ステップから構成されます。ほかのステップは許可されません。包含されるステップは、スナップショットブロックで宣言されたローカルパラメータおよびローカル変数と、隠蔽されていない component 置換変数を参照できます。