この章では、N1 Grid Service Provisioning System software コンポーネントの XML スキーマについて説明します。以下の内容を説明します。
特に断りのない限り、この章で説明する属性は、コンポーネントスコープの置換変数を参照できません。
プロビジョニングソフトウェア の XML スキーマアーキテクチャーについての概要は、第 1 章「XML スキーマの概要」を参照してください。
コンポーネントは、<component> 要素で囲まれます。1 つのコンポーネントのバージョンはすべて、同じ名前とパスを持つ必要があります。この要素の属性は、コンポーネントスコープ置換変数を参照できます。
<component> 要素には次の子要素があり、記載順で出現する必要があります。これらの子要素は、独自の子要素や属性 (両方も可能) を持つことができます。
<component> 要素には次の属性があります。
xmlns:xsi – 値 http://www.w3.org/2001/XMLSchema-instance を持つ必須文字列。
xsi:schemaLocation – オプション文字列。推奨値は http://www.sun.com/schema/SPS component.xsd です。
access – オプション属性で、コンポーネントのアクセシビリティを指定します。次の 3 つの値が有効です。
PATH – コンポーネントを参照できるのはそのコンポーネントと同じパス内に存在するほかのコンポーネントだけです。当該コンポーネントを直接インストールすることはできず、入れ子になった参照を使用してほかのコンポーネントに当該コンポーネントを含めることしかできません。
PUBLIC – コンポーネントは任意のコンポーネントから参照でき、PATH では課せられる制限にも制約されません。これがデフォルト値です。
modifier – modifierEnum 型のオプション値で、コンポーネントに関する次のオーバーライド要件を指定します。
ABSTRACT – コンポーネントを抽象コンポーネントに指定します。抽象コンポーネントは、ほかのコンポーネントを拡張するためのベースコンポーネントとしてのみ機能し、インストールできません。抽象的な子要素を宣言できるのは抽象コンポーネントだけです。
FINAL – コンポーネントを最終コンポーネントとして指定します。これは、そのコンポーネントは別のコンポーネントによる拡張が不可能であることを意味します。
この属性を指定しないと、コンポーネントの拡張とインストールが行えます (これがデフォルト)。
path – pathName 型のオプション値で、コンポーネントの絶対パス。この属性を指定しないと、ルートパス (/) がデフォルト値になります。値の名前は、コンポーネントが保存された時点で存在するフォルダである必要があります。
softwareVendor – オプション文字列で、当該コンポーネントでモデル化されたソフトウェアアプリケーションのベンダー名。
version – schemaVersion 型の必須値で、コンポーネントスキーマのバージョン。現在許可されている値は 5.0 のみです。
platform – オプション文字列で、当該コンポーネントのインストール先として有効な物理ターゲットであるホストを含むホストセットの名前を指定します。
この属性を指定しないと、Remote Agent を含み、サポートされているプラットフォームである、すべてのホストが有効な物理ターゲットになります。この属性を指定する場合、当該コンポーネントをインストールするプランの物理ターゲットは、指定されたホストセットに含まれるホストのサブセットでなければなりません。指定されたホストセットの一部ではないホストが物理ターゲットに含まれる場合、プランは実行時エラーを出力します。このようなプラン実行時エラーは、プリフライトエラーとして報告されます。サポートされているプラットフォームホストセットに対応しない名前を指定した場合、コンポーネント保存時エラーになります。プラットフォームホストセットにはすべて接頭辞 system# プラグイン名が付けられます。コンポーネントプラットフォームセットがサポートされていない場合、プラットフォームが変更されるまで、新しいバージョンのコンポーネントをチェックすることはできません。サポートされていないプラットフォームホストセットを指す、既存のコンポーネントバージョンに対する操作は失敗します。
limitToHostSet – オプション文字列で、当該プランの有効な対象であるホストを含むホストセットの名前を指定します。
この属性を指定しないと、すべてのホストが有効な対象になります。この属性を指定する場合、指定された対象は、指定のホストセットに含まれるホストのサブセットでなければなりません。指定されたホストセットの一部ではないホストが対象に含まれる場合、プランは実行時エラーを出力します。このようなプラン実行時エラーは、プリフライトエラーとして報告されます。サポートされている既存のホストセットに対応しない名前を指定した場合、コンポーネント保存時エラーが発生します。指定されたホストセットがプラグインにより定義されたホストである場合、pluginName は、ホストセット名に対する接頭辞 ( pluginName# hostSetName など) である必要があります。
platform 属性と limitToHostSet 属性では、2 つの大きな違いがあります。
1 つ目の違いは、platform は事前定義されたプラットフォームホストセットの 1 つを指定するのに対し、limitToHostSet はユーザー定義のホストセットを指定することです。 したがって、カスタムホストセットに基づいてインストールを制限する必要がある場合は limitToHostSet を使用する必要があります。
2 つ目の違いは、コンポーネントの対象を仮想ホストにした場合、limitToHostSet のテストはその仮想ホストに照らして行われるのに対し、platform のテストはその仮想ホストのルート物理ホストに照らして行われることです。
したがって、 limitToHostSet を設定し platform は設定しないという方法をとることで、異なる物理プラットフォーム上に存在する特定の仮想ホスト (複数) にコンポーネントをインストールできます (WebLogic アプリケーションはこの方法を採用)。 ただし、platform を設定し limitToHostSet は設定しないようにすると、指定のプラットフォームを持つ物理ホストをルート (親) とする任意のホスト上にコンポーネントをインストールできます。platform、limitToHostSet の両方を設定すると、両方の範囲を制約できます。
installPath – 必須文字列で、非派生コンポーネントにしか認められません。このパスは、当該コンポーネントのインストール時に使用されます。単純コンポーネントの場合、この値はリソースをインストールするルートディレクトリにも相当します。当該コンポーネントのインスタンスがインストールされる際に、パスは共通書式で保存されます。「共通イントールパスの書式」を参照してください。
installPath 属性と limitToHostSet 属性を除き、component 属性は継承されません。
installPath 属性は継承されます。派生コンポーネントによりオーバーライドすることはできません。しかし、ベースコンポーネントはコンポーネント変数を使用してその値を指定でき、これらの変数の値をオーバーライドできます。
ベースコンポーネントが limitToHostSet を指定しなかった場合だけ、limitToHostSet 属性は継承され、派生コンポーネントでオーバーライドできます。
limitToHostSet 値は、ユーザーによって管理される可変のエンティティを指定します。このため、ホストセットの関係をプラットフォームと同じように考えることはできません。
platform 属性は継承されません。しかし、派生コンポーネントの platform 値はベースコンポーネントの platform 値と同様に、一般的ではありません。派生コンポーネントで platform を指定しない場合は、platform はベースコンポーネントでも指定できません (あるいは any として指定する必要があります)。
<extends> 要素は <component> 要素の子であり、当該コンポーネントの派生元であるベースコンポーネントの宣言に使用されます。ベースコンポーネントは最終になることはできません。この要素を使用する場合、この要素は 1 回しか出現できません。
当該コンポーネントは、ベースコンポーネントの各種の属性と要素を自動的に継承します。コンポーネントは、継承されたデータの特定の部分を選択的にオーバーライドできます。継承とオーバーライドの許可は、当の属性または要素の説明内で指定します。
コンポーネントは、その拡張コンポーネントのインスタンスと言えます。また、ベースコンポーネントをインスタンスとするコンポーネントのインスタンスでもあります。
<extends> 要素には 1 つの子要素 <type> があります。この子要素は必須で、ベースコンポーネントを指定します。<type> 要素は、<component> 要素ごとに必ず 1 回使用する必要があります。
<type> 要素はベースコンポーネントの型を指定します。この要素は、<extends>、<componentRefList>、および <componentRef> 要素の子です。
<type> 要素には、systemName 型の 1 つの必須属性 name があり、これはベース型として機能するシステム型コンポーネントの名前です。指定された型がプラグインにより定義された型である場合、pluginName は pluginName# typeName のように、型名に対する接頭辞である必要があります。
<varList> 要素は <component> 要素のオプションの子です。この要素は、当該コンポーネントと当該コンポーネントに含まれる構成リソースが使用するコンポーネントスコープの置換変数のリストを宣言します。この要素を使用する場合、この要素は 1 回しか出現できません。
<varList> 要素には 1 つの必須子要素 <var> があり、この子要素はコンポーネント置換変数を宣言します。
デフォルトでは、派生コンポーネントはそのベースコンポーネントの、アクセスが可能な <varList> 要素コンテンツを継承します。派生コンポーネントが <varList> を宣言する場合、そのコンテンツはベースコンポーネントのコンテンツと完全に結合されます。派生コンポーネントは新しい <var> 要素を宣言することで継承された要素をオーバーライドできますが、ベースコンポーネントによって宣言された要素を削除することはできません。
<var> 要素は、<component> 要素の子である <varlist> の子です。<var> 要素はコンポーネント置換変数を宣言します。変数の名前と、宣言する必要がある各置換変数の値デフォルト値を指定する必要があります。
デフォルトでは、派生コンポーネントはそのベースコンポーネントのすべてのアクセス可能変数 (アクセスモード、修飾子、デフォルト値、プロンプトなど) を継承します。<var> 要素は <varList> 要素内で 1 回または複数回出現できます。
派生コンポーネントは、ベースコンポーネントから継承されている変数に含まれない名前を使用することで、追加の変数を定義できます。派生コンポーネントは、同じ名前を使用して変数を宣言し直すことにより、継承された非最終変数のプロンプト、デフォルト値、修飾子、アクセスモードなどをオーバーライドできます。変数をオーバーライドする場合は、変数の全コンテンツ (プロンプト、デフォルト値、アクセスモード、修飾子など) を宣言し直す必要があります。デフォルト値は、オーバーライドする変数が非抽象である場合にのみ指定できます。アクセスモードは、ベースコンポーネントのモードよりも厳しくすることはできません。
変数をオーバーライドすると、ベースコンポーネント内の参照も含め、その変数に対する参照はすべてオーバーライドされた値に評価されます。
派生コンポーネントを非抽象と宣言する場合、ベースコンポーネントによって宣言された抽象変数は派生コンポーネントによってオーバーライドする必要があります。
<var> 要素には次の属性があります。
access – accessEnum 型のオプション値で、変数のアクセシビリティを指定します。この属性は次の値を取ることができます。
PUBLIC – アクセスはまったく制限されません。これがデフォルトです。
PROTECTED – アクセスは同じパス内の派生コンポーネントとエンティティに制限されます。
PATH – アクセスは同じパス内のエンティティに制限されます。
PRIVATE – アクセスは当該コンポーネントに制限されます。
modifier – modifierEnum 型のオプション値で、変数のオーバーライド要件を指定します。この属性は次の値を取ることができます。
ABSTRACT – 変数の default 属性は省略されます。このため、この属性は 非抽象派生コンポーネントによって指定する必要があります。変数を抽象と宣言できるのは、コンポーネントも抽象と宣言されている場合だけです。抽象変数は専用には設定できません。非抽象変数は、デフォルト値を宣言する必要があります。
FINAL – 変数を派生コンポーネントによってオーバーライドすることはできません。
この属性を指定しない場合、派生コンポーネントは変数をオーバーライドするかどうかを選択できます。
name – identifier 型の必須値で、置換変数の名前。<varList> 要素内の <var> 要素により宣言される各変数名は一意でなければなりません。
default – 非抽象変数用の必須文字列で、置換変数のデフォルト値。この値には、ほかの置換変数、セッション変数、ターゲットホスト属性、インストールされているコンポーネント変数に対する参照を含めることができます。ただし、抽象変数はデフォルト値を定義できないため、この属性は抽象変数には使用できません。
<targetRef> 要素は、<component> 要素のオプションの子です。この要素は、コンポーネントが対象設定可能であることを宣言します。対象設定可能コンポーネントは、インストール時にコンポーネントと関連付けられる物理ホストまたは仮想ホストを自動的に作成するコンポーネントです。この要素は、使用する際には、<varList> 要素の直後に 1 回だけ出現できます。この要素は、単純コンポーネントと複合コンポーネントの両方で使用できます。ただし、<varList> 要素は、最上位コンポーネントとしてインストールされているコンポーネントでのみ使用できます。
<targetRef> 要素には、オプションの子要素 <agent> があり、これは関連付けられたホストが物理ホストと仮想ホストのどちらであるかを示します。<agent> 要素が存在する場合、ホストは物理ホストです。要素の本体は、Remote Agent の構成を定義します。この要素が存在しない場合、ホストは仮想ホストです (これがデフォルト)。
<targetRef> 要素には次の属性があります。
hostName – 必須値で、当該コンポーネントのインストール時に作成するホスト名。この名前はインストール時に一意であり、また有効なホスト名でなければなりません。この値には、コンポーネントスコープの置換変数参照を含めることができます。
typeName – systemName 型のオプション値で、関連付けられたホストに使用するホスト型の名前。コンポーネントの保存時には、指定された型が存在する必要があります。このホスト型がプラグインによって定義されている場合、その名前には「pluginName # typeName」のように、接頭辞として pluginName が含まれている必要があります。
この属性を指定しないと、値は system#crhost になります。
<agent> 要素は、<targetRef> 要素の子です。この要素は、関連付けられたホストが物理ホストであることを示します。この要素はオプションで、1 回しか使用できません。
この要素を指定しないと、関連付けられるホストは仮想ホストとして作成されます。この要素を使用する場合、関連付けられるホストは物理ホストとして作成され、<agent> 要素が、関連付けられる Remote Agent の構成を指定します。
この要素は派生コンポーネントによって継承されます。ベースコンポーネントが宣言を行っていない場合にのみ、派生コンポーネントはローカルな <targetRef> 要素を宣言できます。これは、派生コンポーネントが、継承された <targetRef> 要素をオーバーライドできないことを意味します。
<agent> 要素には次の属性があります。これらの属性は、コンポーネントスコープの置換変数を参照できます。
connection – 必須値で、Remote Agent への接続に使用される接続型を指定します。この属性は次のいずれかの値を取ることができます。
RAW
SSL
SSH
ipAddr – 必須値で、物理ホストの IP アドレス。この値には、サーバー名と IP アドレスのいずれかを使用できます。サーバー名は、Master Server によって IP アドレスに解決できる必要があります。
port – オプション値で、Remote Agent の監視対象であるポート。connection が RAW または SSL である場合、port のデフォルト値は 1131 です。connection が SSH である場合、この属性は無視されます。
<resourceRef> 要素は <component> 要素のオプションの子であり、当該コンポーネントによって管理されるリソースを指定します。この要素を使用できるのは単純コンポーネントのみです。この要素は、複合コンポーネントのみが使用できる<componentRefList> 要素とは併用できません。この要素およびその子の構成可能属性は、コンポーネント置換変数を参照できます。リソースは、暗黙の PUBLIC アクセスモードを取ります。この要素を使用する場合、この要素は 1 回しか出現できません。
コンポーネントが単純コンポーネントから派生する場合、あるいは <resourceRef> 要素を含む非派生コンポーネントである場合、そのコンポーネントは単純コンポーネントになります。派生コンポーネントが単純コンポーネントから派生している場合、その派生コンポーネントに含めることができるのは <resourceRef> 要素だけです。
<resourceRef> 要素には子要素があり、それらは次の順序で出現する必要があります。
<installSpec> – 非派生コンポーネント用の必須要素で、リソースのインストール方法を指定します。この要素を派生コンポーネントに含めることはできません。
<resource> – 非抽象コンポーネント用の必須要素で、関連付けられたリソースを特定します。この要素を抽象的なコンポーネントに含めることはできません。
デフォルトでは、派生コンポーネントはそのベースコンポーネントの <resourceRef> 要素を継承します。
派生コンポーネントは、<resourceRef> 要素を宣言し直すことによって、継承された非最終 <resourceRef> 要素の修飾子と <resource> 要素をオーバーライドできます。<resourceRef> 要素がオーバーライドされる際に、<installSpec> 要素は除外されます。これはそのコンテンツをオーバーライドすることができないためです。<resource> 要素が指定されるのは、優先する <resourceRef> が抽象でない場合だけです。
<resourceRef> がオーバーライドされる際に、ベースコンポーネント内の使用も含め、リソースの使用 (<deployResource>、 <addResource> など) はすべてオーバーライドされた値に解決されます。
派生コンポーネントが非抽象と宣言された場合で、ベースコンポーネントの <resourceRef> 要素が抽象のとき、その派生コンポーネントは <resourceRef> 要素をオーバーライドする必要があります。
<resourceRef> 要素には 1 つのオプション属性 modifierがあり、この属性は modifierEnum 型の値を持っています。modifier 属性は次のように、リソースのオーバーライド要件を指定します。
ABSTRACT – <resourceRef> の <resource> 要素は省略されます。このため、この要素は非抽象派生コンポーネントによって指定する必要があります。<resourceRef> を抽象と宣言できるのは、コンポーネントも抽象と宣言されている場合だけです。非抽象 <resourceRef> は、<resource> 要素を宣言する必要があります。
FINAL – 派生コンポーネントで <resourceRef> をオーバーライドすることはできません。
この属性を指定しない場合、派生コンポーネントは <resourceRef> をオーバーライドするかどうかを選択できます。
<installSpec> 要素は <resourceRef> 要素の子であり、関連付けられたリソースのインストール方法を指定します。この要素は派生コンポーネントによって継承され、オーバーライドできません。しかし、ベースコンポーネントは <installSpec> 属性の値指定にコンポーネント変数を使用でき、これらの変数の値はオーバーライドできます。
<installSpec> 要素には次の属性があります。これらの属性は、コンポーネントスコープの置換変数を参照できます。
path – オプション文字列で、リソースのインストール先となるパス。相対ディレクトリは、包含コンポーネントの installPath 属性に相対的であると見なされます。この引数を指定しないと、デフォルトでコンポーネントの installPath 属性が使用されます。
permissions – オプション文字列で、インストール時に当該リソースに割り当てるアクセス許可を示します。
文字列の書式は、UNIX chmod コマンドでコマンドで定義されているように 3 桁の 8 進数を使用します。chmod(1M) のマニュアルページを参照してください。この属性を指定しないと、リソースはデフォルトのアクセス許可でインストールされます。
user – オプション文字列で、インストール時の当該リソースの所有者。この属性を指定しないと、ユーザーはプラン実行機能 (plan executor) によって決定されます。
group – オプション文字列で、インストール時に当該リソースに割り当てるグループ。この属性を指定しないと、グループはプラン実行機能 (plan executor) によって決定されます。
deployMode – オプション属性で、関連付けられたディレクトリリソースの配備方法を指定します。リソースがディレクトリでない場合、この属性は無視されます。
ADD_TO – 対象ディレクトリ内の任意の既存ファイルにディレクトリコンテンツが追加されます。
REPLACE – 対象ディレクトリ内のすべての既存ファイルがディレクトリコンテンツによって置き換えられます。
この引数を指定しない場合、デフォルト値 REPLACE が使用されます。
diffDeploy – boolean 型のオプション値で、リソースを差分配備モードで配備すべきかどうかを指定します。この属性を指定しないと、差分配備モードが無効になります。差分配備モードを有効にした場合、それまでに配備されたことがないリソースだけが配備されます。
<resource> 要素は <resourceRef> 要素の子であり、当該コンポーネントによって配備されるリソースを特定します。
参照されたリソースが構成可能なリソースである場合、包含コンポーネントにアクセス可能な任意のコンポーネントスコープ変数に対する置換変数参照を含むことができます。
<resource> 要素には次の属性があります。
<componentRefList> 要素は <component> 要素のオプションの子であり、当該コンポーネントによって参照されるコンポーネントの一覧を指定します。この要素は、<resourceRef> 要素とは併用できません。この要素およびその子の構成可能属性は、コンポーネント置換変数を参照できます。この要素を使用する場合、この要素は 1 回しか出現できません。
コンポーネントが複合コンポーネントから派生する場合、あるいは <resourceRef> 要素を含まない非派生コンポーネントである場合、そのコンポーネントは複合コンポーネントになります。派生コンポーネントが複合コンポーネントから派生している場合、その派生コンポーネントに含めることができるのは <componentRefList> 要素だけです。
<componentRefList> 要素には、次のオプションの子要素があります。
<type> – すべての参照先コンポーネントがインスタンスとなるべき型を指定します。この要素を指定しないと、参照先コンポーネントは任意の型になります。
この要素はオプションです。この要素を使用する場合、この要素は <componentRefList> 要素 1 つにつき 1 回しか出現できません。
<componentRef> – コンポーネントに対する参照。この要素はオプションです。この要素を使用する場合、この要素は複数回出現することができます。
デフォルトでは、派生コンポーネントはそのベースコンポーネントの <componentRefList> 要素のコンテンツを継承します。派生コンポーネントが <componentRefList> を宣言する場合、そのコンテンツはベースコンポーネントのコンテンツと完全に結合されます。派生コンポーネントは、新しい <componentRef> 要素を宣言することで継承された要素をオーバーライドできます。ベースコンポーネントによって宣言された要素を削除することはできません。
派生コンポーネントは、親コンポーネントの <componentRefList> 要素によって宣言されている <type> 要素をオーバーライドできます。このためには、<componentRefList> 内の <type> 属性を宣言し直します。この場合、オーバーライドされる型は、オリジナルの型のインスタンスであるか、あるいはオリジナルの型が指定されている必要があります。さらに、すべての参照先コンポーネント (ベースコンポーネントから継承されるものを含む) はオーバーライドされる型のインスタンスでなければなりません。
<componentRefList> 要素には 1 つのオプション属性 modifier があり、これはリソースのオーバーライド要件を指定します。この属性を指定する場合、値は FINAL でなければなりませんが、これは派生コンポーネントが新しい <componentRef> 要素を宣言できないことを意味します。
この属性を指定しない場合、派生コンポーネントは新しい <componentRef> 要素を追加できます。どちらの場合も、派生コンポーネントは <type> 要素と非最終継承 <componentRef> 要素をオーバーライドできます。ベースコンポーネントの <componentRefList> modifier 属性が FINAL である場合、派生コンポーネントの modifier 属性も FINAL である必要があります。
<componentRefList> 要素の modifier が FINAL である場合、含まれる各 <componentRef> の modifier 属性は必ずしも FINAL ではありません。
<componentRef> 要素は <componentRefList> 要素の子で、当該コンポーネントによって参照されるコンポーネントを指定します。この要素は、暗黙的に PUBLIC アクセスとなります。
<componentRef> 要素には子要素があり、それらは次の順序で出現する必要があります。
<type> – 参照先コンポーネントがインスタンスとなるべきコンポーネント型を指定します。これは、包含する <componentRefList> によって指定されるコンポーネント型のインスタンスでなければなりません。
この要素はオプションです。この要素を使用する場合、この要素は <componentRef> 要素 1 つにつき 1 回しか出現できません。
この要素を指定しないと、包含する <componentRefList> によって指定されたコンポーネント型が使用されます。
<argList> – オプション要素で、参照先コンポーネントのインストール時にそれらのコンポーネント変数設定として使用される値の一覧。
この要素を使用する場合、この要素は <componentRef> 要素の子としてのみ 1 回しか出現できません。
<component> – 必須要素で、参照先コンポーネントを指定します。この要素は、抽象 <componentRef> 要素では使用できません。
デフォルトでは、派生コンポーネントはそのベースコンポーネントのすべてのコンポーネント参照を継承します。
ベースコンポーネントの <componentRefList> 要素が最終でない場合、派生コンポーネントはベースコンポーネントから継承されたコンポーネント参照に使用されていない名前を使用して、別のコンポーネント参照を定義できます。
派生コンポーネントは、同じ名前を持つコンポーネント参照を宣言し直すことにより、非最終継承コンポーネント参照のコンポーネント参照をオーバーライドできます。コンポーネント参照がオーバーライドされた場合には、コンポーネント参照の全コンテンツを宣言し直す必要があります。オーバーライドする installMode は、オリジナルの参照のものと同じでなければなりません。オーバーライドする <type> 要素は、オリジナルの型のインスタンスでなければなりません。オーバーライドする <argList> 要素は、オリジナルのものと結合されます。詳細は、「<argList> 要素」を参照してください。<component> 要素は、オーバーライドする参照が非抽象の場合にのみ指定されます。
コンポーネント参照をオーバーライドすると、ベースコンポーネント内のものも含め、そのコンポーネント参照の使用はすべてオーバーライド値に評価されます。
派生コンポーネントを非抽象と宣言する場合、ベースコンポーネントによって宣言された抽象的なコンポーネント参照は、派生コンポーネントによってオーバーライドする必要があります。
<componentRef> 要素には次の属性があります。
modifier – modifierEnum 型のオプション属性で、コンポーネント参照のオーバーライド要件を指定します。この属性は次の値を取ります。
ABSTRACT – <componentRef> 要素の <component> 子要素は省略されるため、非抽象派生コンポーネントによって指定する必要があります。<componentRef> を抽象と宣言できるのは、そのコンポーネントも抽象と宣言されている場合だけです。非抽象 <componentRef> は、<component> 要素を宣言する必要があります。
FINAL – <componentRef> は派生コンポーネントによってはオーバーライドできません。
この属性を指定しない場合、派生コンポーネントはコンポーネント参照をオーバーライドするかどうかを選択できます。
name – identifier 型の必須属性で、参照先コンポーネントのローカル名を指定します。この名前は、すべての兄弟 <componentRef> 要素の中で一意となるようにする必要があります。
installMode – オプション属性で、参照先コンポーネントをインストールし、その後対象設定を行う方法を指定します。この属性を指定しないと、値は NESTED になります。
この属性は次の値を取ります。
TOPLEVEL – 参照先コンポーネントが TOPLEVEL としてインストールされている場合、1 つのプランで直接インストールされたかのように、ほかの任意のコンポーネントがそのコンポーネントを使用できます。
NESTED – 参照先コンポーネントが NESTED としてインストールされている場合、そのインストールの範囲は参照元コンポーネントのインストール範囲に暗黙に限定されます。そのサービスも参照元コンポーネントでしか利用できません。
論理的に、入れ子になった参照先コンポーネントは参照元コンポーネントが要求する細かな機能単位を定義しますが、この機能はほかのコンポーネントに役立つことはありません。一方、最上位の参照先コンポーネントは参照元コンポーネントが使用するサービスを定義しますが、ほかのコンポーネントもこのサービスを使用できます。
入れ子になった参照先コンポーネントの有効期間は、参照元コンポーネントの有効期間と暗黙に同じになります。入れ子になった参照先コンポーネントのインストールは参照元コンポーネントのインストールの最中にしか行えず、参照元コンポーネントがアンインストールされる際に暗黙にアンインストールされます。これに対し、最上位の参照先コンポーネントの有効期間は、参照元コンポーネントの有効期間には拘束されていません。最上位の参照先コンポーネントは、参照元コンポーネントのインストール時に参照元コンポーネントによってインストールすることができます。また、最上位の参照先コンポーネントがすでにインストールされている場合は、ほかの方法でインストールすることもできます。参照元コンポーネントがアンインストールされる場合、明示的に参照元コンポーネントによってアンインストールされない限り、最上位の参照先コンポーネントはインストールされたままとなります。 また、ほかのコンポーネントも参照元コンポーネントをアンインストールできます。
<targetRef> 要素を定義するコンポーネントを参照するには、TOPLEVEL <componentRef> を使用する必要があります。NESTED <componentRef> は使用できません。
<argList> 要素は <componentRef> 要素の子で、参照先コンポーネントのインストール時に、そのコンポーネント変数設定として使用される値の一覧を指定します。この <argList> の書式は、 <call> ステップの <argList> 子要素の書式と同じです。詳細は、「<call> ステップ」を参照してください。
参照が ABSTRACT の場合、<argList> 要素の各属性は、参照先コンポーネントにおけるコンポーネント変数または宣言された型を指定します。<argList> 要素の属性の値は、参照先コンポーネントのインストール時に、指定されたコンポーネント変数に使用されるオーバーライド値です。
コンポーネント参照が派生コンポーネントによってオーバーライドされる場合、ベースコンポーネントおよび派生コンポーネントの <argList> 要素は、効率よく結合されます。この結合は、ベースコンポーネントの <argList> のコンテンツを参照先コンポーネントに適用し、続いて派生コンポーネントの <argList> を適用することによって行われます。ベースコンポーネント参照の <argList> を処理する場合、考慮されるのはベースコンポーネント参照の宣言された型で定義された変数だけです。
<argList> で指定されていないコンポーネント変数は、インストール時にそれらのデフォルト値を使用します。<argList> が指定されていない場合、参照先コンポーネントがインストールされ、またそのすべての変数のデフォルト値を使用します。<argList> で指定される参照先コンポーネントの変数は、参照元コンポーネントからアクセス可能でなければなりません。また、これらの変数はアクセスモード FINAL ではなく、PUBLIC または PROTECTED で宣言されていなければなりません。
最上位の参照先コンポーネントの場合、<argList> 要素が使用されるのは参照先コンポーネントが参照元コンポーネントによってインストールされている場合だけです。参照先コンポーネントは、ほかの方法でインストールされていることもあります。この場合、<argList> は意味を持ちません。
<component> 要素は <componentRef> 要素の子で、参照先コンポーネントを特定します。この要素の構造は、host 属性が許可されない点を除き、<component> リポジトリコンポーネントターゲッターと同じです。参照先コンポーネントバージョンは、包含コンポーネントの保存時にリポジトリ内に存在する必要があります。
version 属性を指定しないと、version は包含コンポーネントの保存時に存在する参照先コンポーネントの最新バージョンに解決されます。参照先コンポーネントのバージョンが存在しない場合、保存時のエラーが発生します。包含コンポーネントが保存されると、当該コンポーネントが参照するすべてのコンポーネントのバージョンがロックされます。参照先コンポーネントは、コンテナコンポーネントの新しいバージョンを作成しない限り変更できません。
<installList> 要素は <component> 要素の子であり、1 つ以上の名前付きインストールステップブロックを含みます。各ブロックは、当該コンポーネントをインストールする個々の方法を提供します。多くのコンポーネントには、<installSteps> 要素の子としてインストールブロックが1 つだけ存在します (この節で後述)。
この要素は、非派生コンポーネントの場合は必須で、派生コンポーネントの場合はオプションです。この要素を使用する場合、この要素は 1 回しか出現できません。
インストール環境ごとに異なるステップが必要な場合は、複数のインストールブロックを使用できます。たとえば、EBJ アプリケーションをサーバークラスタに配備するインストールブロック、単一の管理対象サーバーに配備する別のインストールブロック、最初のインストール用のインストールブロック、およびアプリケーションをアップグレードするインストールブロックを作成できます。
デフォルトでは、派生コンポーネントはそのベースコンポーネントの、アクセスが可能な <installList> 要素コンテンツを継承します。派生コンポーネントが <installList> を宣言する場合、そのコンテンツはベースコンポーネントのコンテンツと完全に結合されます。派生コンポーネントは新しい <installSteps> 要素を宣言することで継承された要素をオーバーライドできますが、ベースコンポーネントによって宣言された要素を削除することはできません。
<installList> 要素には 1 つの子要素 <installSteps> があり、この子要素は、当該コンポーネントをインストールするために実行されるステップのシーケンスを一覧表示します。<installSteps> 要素は、1 回または複数回出現することができます。
<installList> 要素には 1 つの子要素 <installSteps> があり、この子要素は、当該コンポーネントをインストールするために実行されるステップのシーケンスを一覧表示します。<install> ステップによって当該コンポーネントがインストールされる場合、ここに挙げるステップが順に実行されます。一般に、単純コンポーネントのインストールステップには <deployResource> ステップが含まれます。複合コンポーネントのインストールステップには、参照先コンポーネントをインストールするため、1 つ以上の <install> ステップが含まれます。
<installSteps> 要素の子は、オプションの <paramList> 要素から構成され、このあとには本体が続き、これはオプションのローカル <varList> 要素から構成されています。ローカル <varList> 要素には、ゼロ個以上の「共通」ステップまたは「コンポーネントのインストール専用」ステップが続きます。インストールブロックが抽象と宣言されている場合、本体は含められません。
デフォルトでは、派生コンポーネントはそのベースコンポーネントの、アクセス可能なすべてのインストールブロックを継承します。
派生コンポーネントは、ベースコンポーネントから継承されたインストールブロックに含まれない名前を使用して別のインストールブロックを定義できます。派生コンポーネントは、同じ名前を使用してブロックを宣言し直すことにより、継承した非最終インストールブロックをオーバーライドできます。ブロックの無効化は名前を使用してしか行えず、パラメータに基づいてオーバーロード(多重定義) することはできません。ブロックをオーバーライドする場合は、ブロックの全コンテンツ (アクセスモード、修飾子、およびパラメータ) を宣言し直す必要があります。本体を指定できるのは、優先するブロックが非抽象の場合だけです。アクセスモードは、ベースコンポーネントのモードよりも厳しくすることはできません。
派生コンポーネント内の優先ブロックのシグニチャーは、ベースコンポーネントのシグニチャーと互換性がなければなりません。互換性があるということは、ベースブロックが使用できる引数はすべて派生ブロックでも使用できることを意味します。
派生ブロックがベースブロックと互換性があるのは、必須パラメータを新たに宣言せず、親ブロックでオプションパラメータを必須パラメータとして再定義していない場合です。
以下のシグニチャー変更は互換性があると見なされます。
必須パラメータまたはオプションパラメータの削除
必須パラメータのオプションパラメータへの変更
オプションパラメータの追加
ブロックをオーバーライドすると、ベースコンポーネント内の参照も含め、そのブロックに対する参照はすべてオーバーライドされた値に評価されます。
派生コンポーネントを非抽象と宣言する場合は、ベースコンポーネントによって宣言されているすべての抽象ブロックを、派生コンポーネントによってオーバーライドする必要があります。
<superComponent> ターゲッターを使用して派生コンポーネントがブロックをオーバーライドする場合でも、派生コンポーネント内のブロックは、ベースコンポーネントによって定義されているブロックを明示的に呼び出すことができます。
<installSteps> 要素には次の属性があります。
access – accessEnum 型のオプション属性で、インストールブロックのアクセシビリティを指定します。次の値が使用できます。
PUBLIC – アクセスはまったく制限されません。デフォルトのアクセスモードです。
PROTECTED – アクセスは同じパス内の派生コンポーネントとエンティティに制限されます。
PATH – アクセスは同じパス内のエンティティに制限されます。
PRIVATE – アクセスは当該コンポーネントに制限されます。
コンポーネントから直接実行できるのは PUBLIC ブロックだけです。
modifier – ModifierEnum 型のオプション属性で、インストールブロックのオーバーライド要件を指定します。次の値が使用できます。
ABSTRACT – ブロックに本体を含めることはできません。本体は、非抽象派生コンポーネントによって指定する必要があります。インストールブロックを抽象と宣言できるのは、コンポーネントも抽象と宣言されている場合だけです。抽象ブロックは専用にはできません。非抽象ブロックの場合、本体を宣言する必要があります。
FINAL – インストールブロックを派生コンポーネントによってオーバーライドすることはできません。
modifier 属性を指定しない場合、派生コンポーネントはブロックをオーバーライドするかどうかを選択できます。
name – entityName 型の必須属性で、インストールブロックの名前。この名前は、包含している <installList> 内のすべてのインストールブロックの中で一意である必要があります。
<paramList> 要素は、<installSteps>、<uninstallSteps>、<snapshot>、および <control> 要素の子です。この要素は、包含要素のステップで使用できるパラメータの一覧を宣言します。パラメータの値は、呼び出し側の <argList> 要素のコンテンツに基づいて呼び出し側によって定義されます。たとえば、<installSteps> ブロック内の <paramList> の場合、パラメータ値は <installSteps> ブロックを呼び出した <install> ステップの <argList> に基づいて定義されます。
包含要素のステップは、次の変数とパラメータを使用できます。
ローカル <varList> 要素で宣言されたローカルスコープ変数
<paramList> 要素で宣言されたパラメータ
包含コンポーネントのコンポーネント <varList> 要素で宣言されたコンポーネントスコープ変数
<paramList> パラメータの名前がコンポーネント <varList> 変数と同じである場合、パラメータの値が使用されます。このような場合、パラメータはコンポーネント変数を「隠蔽」していると言われます。隠蔽は、ローカル変数とパラメータの間では許可されません。これは、それらの名前が個別のものでなければならないためです。
<paramList> 要素には 1 つの必須子要素 <param> があります。この子要素はパラメータ宣言で、名前とデフォルト値が含まれます。定義する必要があるパラメータごとに、1 つの <param> 要素を指定します。
<param> 要素は <paramList> 要素の子で、(名前、デフォルト値が含まれる) パラメータを宣言します。デフォルト値が使用されるのは、呼び出し側がこのパラメータの値を明示的に渡さない場合だけです。デフォルト値が指定されず、呼び出し側がこのパラメータの値を明示的に渡さない場合、プランの実行時にプリフライトエラーが発生します。
<param> 要素には次の属性が含まれます。包含しているインストールブロック、アンインストールブロック、または制御ブロックが、プランまたはほかのコンポーネントからではなくユーザーによって直接呼び出される場合に、prompt 属性および displayMode 属性を使用します。
name – identifier 型の必須属性で、パラメータの名前。この名前は、包含要素によって宣言されているほかのすべてのローカル変数とパラメータにおいて一意でなければなりません。
prompt – オプション属性で、パラメータの値を求める際にユーザインタフェースで表示されるテキストを指定する文字列。この属性を指定しないと、name の値が使用されます。
default – オプション属性で、パラメータのデフォルト値を指定する文字列。パラメータには、コンポーネント変数、ターゲットホスト属性、セッション変数、およびインストール済みコンポーネント変数への参照を含めることができますが、ほかのパラメータへの参照を含めることはできません。
displayMode – オプション属性で、パラメータの表示モードを指定します。次の値が有効です。
PASSWORD – ユーザー指定の値が隠されます。つまりパスワードは表示されないか、アスタリスクに置き換えられます。
BOOLEAN – チェックボックスを使用してパラメータが指定されます。
CLEAR – 入力時に値が表示されます。
値が CLEAR または BOOLEAN の場合は、入力時に安全に表示されます。この属性を指定しないと、値は CLEAR になります。
ローカル <varList> 要素は、<installSteps>、<uninstallSteps>、<snapshot>、および <control> 要素の子です。この要素は、包含要素のステップで使用できる変数の一覧を宣言します。これらの変数の値は宣言時に定義され、再定義は行えません。
包含要素のステップは、次の変数とパラメータを使用できます。
ローカル <varList> 要素で宣言されたローカルスコープ変数
<paramList> 要素で宣言されたパラメータ
包含コンポーネントのコンポーネント <varList> 要素で宣言されたコンポーネントスコープ変数
ローカル <varList> 変数の名前がコンポーネント <varList> 変数と同じである場合、ローカル変数の値が使用されます。このような場合、ローカル変数はコンポーネント変数を「隠蔽」していると言われます。隠蔽は、ローカル変数とパラメータの間では許可されません。これは、それらの名前が個別のものでなければならないためです。
ローカル <varList> 要素には 1 つの必須子要素 <var> があります。この要素は、ローカル変数 (名前、デフォルト値など) の宣言です。複数の <var> 要素を指定できます。
<uninstallList> 要素は <component> 要素の子です。この要素は 1 つ以上の名前付き <uninstall> ステップブロックを含み、 各ブロックは、当該コンポーネントをアンインストールする個々の方法を提供します。多くのコンポーネントには、この要素の子としてアンインストールブロックが 1 つだけ存在します。インストール環境ごとに異なるステップが必要な場合は、複数のアンインストールブロックを使用できます。
たとえば、EBJ アプリケーションの配備をサーバークラスタから解除するアンインストールブロックや、単一の管理対象サーバーから解除するアンインストールブロックなどが作成できます。アンインストールブロックは、インストールブロックと一対一で対応していることが少なくありません。このような場合には、慣習上同じ名前を使用して対応を示してください。
この要素は、非派生コンポーネントの場合は必須で、派生コンポーネントの場合はオプションです。この要素を使用する場合、この要素は 1 回しか出現できません。
<uninstallList> 要素には 1 つの必須子要素 <uninstallSteps> があります。この子要素は、当該コンポーネントをアンインストールするために実行できるステップを含む、名前付きのアンインストールブロックです。コンポーネントをアンインストールする各方法に対して、それぞれ 1 つの <uninstallSteps> 要素を指定します。
デフォルトでは、派生コンポーネントはベースコンポーネントのアクセス可能な <uninstallList> 要素コンテンツを継承します。派生コンポーネントが <uninstallList> を宣言する場合、そのコンテンツはベースコンポーネントのコンテンツと完全に結合されます。派生コンポーネントは新しい <uninstallSteps> 要素を宣言することで継承された要素をオーバーライドできますが、ベースコンポーネントによって宣言された要素を削除することはできません。
<uninstallSteps> 要素は <uninstallList> 要素の子であり、当該コンポーネントをアンインストールするために実行される一連のステップを示します。<uninstall> ステップによって当該コンポーネントがアンインストールされる場合、この要素に挙げられるステップが順に実行されます。単純コンポーネントの <uninstallSteps> 要素は <undeployResource> ステップを含むことが許可されていますが、これは必須ではありません。複合コンポーネントの <uninstallSteps> 要素は、参照先コンポーネントをアンインストールするため、1 つ以上の <uninstall> ステップが含むことができますが、これらのステップは必須ではありません。
<uninstallSteps> 要素の子は、オプションの <paramList> 要素とそれに続く本体から構成されます。この本体は、オプションのローカル <varList> 要素と、それに続くオプションの <dependantCleanup> ブロックおよびゼロ個以上の「共通」ステップまたは「コンポーネントのアンインストール専用」ステップから構成されます。アンインストールブロックが抽象と宣言されている場合、本体は含められません。
次の例に、サンプル <uninstallSteps> 要素のコンテンツを示します。</paramList> 以降が本体を定義しています。
<uninstallSteps name="default"> <paramList> <param name="param1"/> </paramList> <varList> <var name="var1" default="my var 1"/> </varList> <dependantCleanup> <uninstall blockName="default"> <allDependants name="child2parent"/> </unisntall> </dependantCleanup> <undeployResource/> </uninstallSteps>
デフォルトでは、派生コンポーネントはそのベースコンポーネントの、アクセス可能なすべてのアンインストールブロックを継承します。アンインストールブロックをオーバーライドするセマンティクスは、インストールブロックをオーバーライドするセマンティクスと同じです。
<uninstallSteps> 要素には次の属性があります。
access – accessEnum 型のオプション属性で、アンインストールブロックのアクセシビリティを指定します。次の値が使用できます。
PUBLIC – アクセスは制限されません。これがデフォルトです。
PROTECTED – アクセスは同じパス内の派生コンポーネントとエンティティに制限されます。
PATH – アクセスは同じパス内のエンティティに制限されます。
PRIVATE – アクセスは当該コンポーネントに制限されます。
コンポーネントから直接実行できるのは PUBLIC ブロックだけです。
modifier – modifierEnum 型のオプション属性で、アンインストールブロックのオーバーライド要件を指定します。次の値が使用できます。
ABSTRACT – ブロックに本体を含めることはできません。 本体は、非抽象派生コンポーネントによって指定する必要があるためです。アンインストールブロックを抽象と宣言できるのは、コンポーネントも抽象と宣言されている場合だけです。抽象ブロックは専用にはできません。非抽象ブロックの場合、本体を宣言する必要があります。
FINAL – アンインストールブロックを派生コンポーネントによってオーバーライドすることはできません。
この属性を指定しない場合、派生コンポーネントはブロックをオーバーライドするかどうかを選択できます。
name – entityName 型の必須属性で、アンインストールブロックの名前。この名前は、包含している <uninstallList> 内のすべてのアンインストールブロックの中で一意である必要があります。
<dependantCleanup> 要素は <uninstallSteps> 要素の子です。<dependantCleanup> 要素は、呼び出し側コンポーネントに現在依存しているコンポーネントを削除するために実行される一連のステップを指定します。この要素に属性はなく、包含するアンインストールブロックのスコープ内で許可される任意の数のステップを含むことができます。
この要素を含めると、依存コンポーネントのチェックはブロックのコンテンツの実行が完了するまで延期されます。ブロックの実行が完了したあとも依存コンポーネントが存在する場合は、アンインストールが失敗し、コンポーネントはインストールされたままとなります。依存コンポーネントが残っていない場合、アンインストールが継続されて残りのステップが行われます。
包含コンポーネントが対象設定可能である場合、ブロックを使用して、ホストを対象とする関連付けられたコンポーネントにインストールされたコンポーネントを削除できます。このブロックが完了したあとも、関連付けられているホスト上にインストール済みコンポーネントが残っている場合、アンインストールは失敗します。
アンインストールブロックに <dependantCleanup> ブロックを含めないと、依存コンポーネントが存在する場合、アンインストールブロックはただちに停止します。
<dependantCleanup> ブロックは、依存コンポーネントをまとめてアンインストールする目的で、し<allDependants> ターゲッターと併用されることもあります。
<snapshotList> 要素は <component> 要素のオプションの子です。この要素には、1 つ以上の名前付きスナップショットブロックが含まれます。各ブロックは、ターゲットホスト上における当該コンポーネントのインストール状態をキャプチャする個別の方法を提供します。複数のスナップショットブロックを使用してインストール状態のさまざまな情報をキャプチャできるため、キャプチャされたインストール状態とコンポーネントの現在の状態を詳しく比較できます。この要素を使用する場合、この要素は 1 回しか出現できません。
この要素には 1 つの必須子要素 <snapshot> があります。これは当該コンポーネントのインストール状態をキャプチャするために実行できる名前付きスナップショットブロックです。1 つ以上の <snapshot> 要素を使用できます。
デフォルトでは、派生コンポーネントはそのベースコンポーネントの、アクセスが可能な <snapshotList> 要素コンテンツを継承します。派生コンポーネントが <snapshotList> を宣言する場合、そのコンテンツはベースコンポーネントのコンテンツと完全に結合されます。派生コンポーネントは新しい <snapshot> 要素を宣言することで継承された要素をオーバーライドできますが、ベースコンポーネントによって宣言された要素を削除することはできません。
<snapshot> 要素は <snapshotList> 要素の子で、当該コンポーネントのインストール状態をキャプチャするために実行される一連のステップを定義します。<createSnapshot> または <addSnapshot> ステップがこのスナップショットブロックを指定する場合、prepare ブロック内のステップが順に実行されます。続いて capture ブロックで指定されたファイルターゲットサーバーのキャプチャ領域でキャプチャされ、最後に cleanup ブロック内のステップが順に実行されます。
スナップショットブロックは、コンポーネントの現在の状態をそのインストール時の状態と比較するためにも使用されます。具体的には、ターゲットサーバーで prepare ステップが再実行され、続いてインストール時にキャプチャされたファイルが現在のファイル状態と比較され、cleanup ステップが再実行されます。
<snapshot> 要素には次の子要素があります。
<paramList> – オプション要素で、当該スナップショットの prepare、capture、および cleanup の各ブロック内で使用するためのパラメータの一覧。この要素は 1 回しか出現できません。
<varList> – オプション要素で、当該スナップショットの prepare、capture、および cleanup の各ブロック内で使用するためのローカル変数の一覧。この要素は 1 回しか出現できません。
<prepare> – オプション要素で、ファイルのキャプチャまたは比較に備えて実行されるステップを含みます。この要素は 1 回しか出現できません。
<capture> – オプション要素で、当該スナップショットの一部としてキャプチャされるファイルおよびディレクトリの一覧を含みます。この要素は 1 回しか出現できません。
<cleanup> – オプション要素で、キャプチャまたは比較の完了後に実行されるステップを含みます。この要素は 1 回しか出現できません。
当該スナップショットが <createSnapshot> ステップから呼び出される場合は、必要なパラメータをその <paramList> 要素で宣言することはできません。
<varList>、 <prepare>、<capture>、および <cleanup> 要素は、集合的にスナップショットの本体を定義します。スナップショットブロックが抽象と宣言される場合、本体は含められません。
デフォルトでは、派生コンポーネントはそのベースコンポーネントの、アクセス可能なすべてのスナップショットブロックを継承します。スナップショットブロックをオーバーライドするセマンティクスは、インストールブロックをオーバーライドするセマンティクスと同じです。
派生コンポーネントスナップショットブロックの prepare ブロックからベースコンポーネントスナップショットブロックの prepare ブロックを呼び出す方法はありません。同じことが cleanup についても言えます。このような呼び出しを行うには、ベースコンポーネントはその <prepare> および <cleanup> ステップを、派生コンポーネントによって呼び出すことができる制御ブロックに含める必要があります。
この要素には次の属性があります。
access – accessEnum 型のオプション属性で、スナップショットブロックのアクセシビリティを指定します。次の値が使用できます。
PUBLIC – アクセスは制限されません。これがデフォルトです。
PROTECTED – アクセスは同じパス内の派生コンポーネントとエンティティに制限されます。
PATH – アクセスは同じパス内のエンティティに制限されます。
PRIVATE – アクセスは当該コンポーネントに制限されます。
modifier – modifierEnum 型のオプション属性で、スナップショットブロックのオーバーライド要件を指定します。次の値が使用できます。
ABSTRACT – ブロックに本体を含めることはできません。 本体は、非抽象派生コンポーネントによって指定する必要があるためです。スナップショットブロックを抽象と宣言できるのは、コンポーネントも抽象と宣言されている場合だけです。抽象ブロックは専用にはできません。非抽象ブロックの場合、本体を宣言する必要があります。
FINAL – スナップショットブロックを派生コンポーネントによってオーバーライドすることはできません。
この属性を指定しない場合、派生コンポーネントはブロックをオーバーライドするかどうかを選択できます。
name – entityName 型の必須属性で、スナップショットブロックの名前です。この名前は、包含している <snapshotList> 内のすべてのスナップショットブロックの中で一意である必要があります。
<prepare> 要素は <snapshot> 要素の子で、ファイルのキャプチャまたは比較に備えた一連のステップを定義します。これらのステップは、当該スナップショットを対象とする <createSnapshot> または <addSnapshot> ステップの結果として、かつ当該スナップショットを対象とする比較作業として実行されます。どのような場合も、これらのステップはファイルのキャプチャまたは比較作業に先立って実行されます。
<prepare> 要素の子は、1 つ以上の <call>、<execNative>、および <transform> ステップから構成されます。ほかのステップは許可されません。包含されるステップは、スナップショットブロックで宣言されたローカルパラメータおよびローカル変数と、隠蔽されていない component 置換変数を参照できます。
<capture> 要素は、当該スナップショットの一部としてキャプチャされるファイルとリソースを定義します。キャプチャは、<prepare> ブロック内のステップが実行されたあとでしか行われません。キャプチャが完了すると、<cleanup> ブロック内のステップが実行されます。
<capture> 要素の子は、1 つ以上の <addFile>、<addSnapshot>、および <addResource> 要素から構成されます。このブロックに挙げられるファイルとディレクトリは、指定された順にキャプチャされます。包含される子は、スナップショットブロックで宣言されたローカルパラメータおよびローカル変数と、隠蔽されていない component 置換変数を参照できます。
<addFile> 要素は <capture> 要素の子であり、包含するスナップショットの一部としてキャプチャされるファイルを指定します。
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> ステップを使用することは、次のシナリオのすべてと意味的に同じです。
呼び出されたスナップショットの <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> 要素は、包含するスナップショットの一部としてキャプチャされるコンポーネントに関連付けられたリソースを指定します。この要素は、単純コンポーネントにしか含めることができません。
この要素は、次に示すように、同等の <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> 要素は <snapshot> 要素の子であり、ファイルのキャプチャまたは比較が完了したあとで実行される一連のステップを定義します。これらのステップは、当該スナップショットを対象とする <createSnapshot> または <addSnapshot> ステップの結果として、かつ当該スナップショットを対象とする比較作業として実行されます。どのような場合も、これらのステップはすべてのファイルのキャプチャまたは比較作業のあとに実行されます。cleanup ブロックは、prepare ブロックで作成された一時ファイルを削除するために使用します。
<cleanup> 要素の子は、1 つ以上の <call>、<execNative>、および <transform> ステップから構成されます。ほかのステップは許可されません。包含されるステップは、スナップショットブロックで宣言されたローカルパラメータおよびローカル変数と、隠蔽されていないコンポーネント置換変数を参照できます。
<controlList> 要素は <component> 要素のオプションの子であり、当該コンポーネントで利用できる制御ブロックをリストします。この要素を使用する場合、この要素は 1 回しか出現できません。
この要素には制御ブロックである必須子要素 <control>があります。複数の <control> 要素を指定できます。
デフォルトでは、派生コンポーネントはそのベースコンポーネントの、アクセスが可能な <controlList> 要素コンテンツを継承します。派生コンポーネントが <controlList> を宣言する場合、そのコンテンツはベースコンポーネントのコンテンツと完全に結合されます。派生コンポーネントは新しい <control> 要素を宣言することで継承された要素をオーバーライドできますが、ベースコンポーネントによって宣言された要素を削除することはできません。
<control> 要素は、当該コンポーネントで利用できる制御ブロックを定義します。制御ブロックは、当該コンポーネントのインストールが完了したあとで実行できる一連のステップです。たとえば、データベースアプリケーションのコンポーネントに制御ブロックを含め、データベースの「起動」または「停止」を行えます。 <call> ステップは、名前で制御ブロックを呼び出すことができます。この呼び出しにより、制御ブロックステップが順に実行されます。
<control> 要素の子は、オプションの <paramList> 要素とそれに続く本体から構成されます。この本体は、オプションのローカル <varList> 要素と、それに続くゼロ個以上の「共通」ステップから構成されます。詳細は、「共有ステップ」を参照してください。制御ブロックが抽象と宣言されている場合、本体は含められません。
デフォルトでは、派生コンポーネントはそのベースコンポーネントの、アクセス可能なすべての制御ブロックを継承します。制御ブロックをオーバーライドするセマンティクスは、インストールブロックをオーバーライドするセマンティクスと同じです。
<control> 要素には次の属性があります。
access – accessEnum 型のオプション属性で、制御ブロックのアクセシビリティを指定します。次の値が有効です。
PUBLIC – アクセスは制限されません。これがデフォルト値です。
PROTECTED – アクセスは同じパス内の派生コンポーネントとエンティティに制限されます。
PATH – アクセスは同じパス内のエンティティに制限されます。
PRIVATE – アクセスは当該コンポーネントに制限されます。
コンポーネントから直接実行できるのは PUBLIC ブロックだけです。
modifier – modifierEnum 型のオプション属性で、制御ブロックのオーバーライド要件を指定します。次の値が有効です。
ABSTRACT – ブロックに本体を含めることはできません。その代わりに本体は、非抽象派生コンポーネントによって指定する必要があります。制御ブロックを抽象と宣言できるのは、コンポーネントも抽象と宣言されている場合だけです。抽象ブロックは専用にはできません。非抽象ブロックの場合、本体を宣言する必要があります。
FINAL – 制御ブロックを派生コンポーネントによってオーバーライドすることはできません。
この属性を指定しない場合、派生コンポーネントはブロックをオーバーライドするかどうかを選択できます。
name – entityName 型の必須属性で、制御ブロックの名前。これは、制御を実行するために <call> ステップから参照されます。
<diff> 要素は <component> 要素のオプションの子です。この要素は、当該コンポーネントで比較を実行する際に比較エンジンによって使用される命令のリストを含みます。この要素を使用する場合、この要素は 1 回しか出現できません。
<diff> 要素には 1 つの必須子要素である <ignore> があります。この要素は、比較の際に無視するディレクトリパスを指定します。<ignore> 要素は、1 回または複数回使用することができます。
派生コンポーネントは、ベースコンポーネントによって宣言されたすべての無視命令を自動的に継承します。また、それ自体の <diff> 要素内で無視命令をさらに宣言することもできます。継承された命令を削除することはできません。
<ignore> 要素は <diff> 要素の子であり、比較で当該コンポーネントを使用する場合に無視するファイル名パスのパターンを指定します。この要素は、一般に、インストールされたアプリケーションによって作成されるファイルとディレクトリ (ログファイルなど) に使用されます。この要素の構成可能属性は、コンポーネント置換変数を参照できます。
<ignore> 要素には 1 つの必須属性 path があります。これは、無視するファイル名パスに一致する glob スタイルのパターンです(例: /logs/*.log) 。この属性は、コンポーネントスコープの置換変数を参照できます。
この節では、コンポーネントのインストールブロック内でしか使用できないステップを示します。
<deployResource> ステップを除くすべてのステップは、単純コンポーネントと複合コンポーネントの両方で使用できます。<deployResource> ステップは、単純コンポーネントのみが使用できます。
このステップは、ほかのコンポーネントに対する現在のコンポーネントの永続的な依存性を作成します。このステップは、その実行時にまず指定された基準に一致するインストール済みコンポーネントが存在しないかチェックします。そのようなコンポーネントが存在しない場合、このステップは停止します (この動作は <checkDependency> ステップに同じ)。一致するコンポーネントが見つかると、一致したコンポーネント (依存先コンポーネント) と呼び出しコンポーネント (依存元コンポーネント) の間に永続的な依存性が作成されます。
複数のインストール済みコンポーネントが基準に一致する場合 (インストールパスを指定しないとこのような状況となり得る) は、最新のものが依存先として使用されます。永続的なコンポーネントは、ステップで指定される名前で作成されます。 この名前は、インストールブロックで作成されるすべての依存性間で一意のものでなければなりません。
作成された永続的な依存性は、依存コンポーネントがアンインストールされるまで持続します。永続的な依存性を作成したあとで後続のステップで依存コンポーネントのインストールが停止する場合、依存性はこの停止時にただちに削除されます。
個々のコンポーネントは、<createDependency> ステップをほかのコンポーネントごとに実行することにより任意の数のコンポーネントに依存できます。依存性が満たされない場合、実際の処理が行われる前にインストールが停止するように、<createDependency> ステップはインストールブロックの最初のステップに指定する必要があります。
<createDependency> ステップには 1 つの必須子要素があり、この要素が依存先コンポーネントを特定します。その子要素はインストール済みコンポーネントターゲッターです。詳細は、「インストール済みコンポーネントターゲッター」を参照してください。
<createDependency> ステップには identifier 型の 1 つの必須属性 name があり、これは作成する依存性の名前です。この名前は、現在のコンポーネントによって作成されるすべての依存性の間で一意のものでなければなりません。
コンポーネントのアンインストールは、そのコンポーネントに対して依存するインストール済みコンポーネントが存在する場合は行えません。コンポーネントのアンインストールブロックが検出された場合で、そのコンポーネントを依存先とする 1 つ以上の永続的な依存性が存在するときは、アンインストールはただちに停止します。
しかし、コンポーネント A によってコンポーネント B のアンインストールが進行している場合、A によって作成された B に対する依存性が B のアンインストールを防止することはなく、この依存性は B が正常にアンインストールされた時点で暗黙に削除されます。
依存先コンポーネントは、<dependantCleanup> ブロックを使用してその依存元 (dependant) をアンインストールするアクションを指定できます。
同じホストとインストールパス上にインストールされた同じバージョンツリー内に既存コンポーネントが存在する場合、コンポーネントのインストールは、再インストールと見なされます。コンポーネントの再インストールが行えるのは、その新しいコンポーネントがオリジナルコンポーネントのすべての依存元に適合する場合だけです。コンポーネントは常に同じバージョンのコンポーネントで再インストールできます。ただし、永続的な依存性を作成した <createDependency> ステップ内で指定した制約に、新しいバージョンが適合する場合には、異なるバージョンで再インストールすることもできます。
コンポーネントの単純インストールブロックが検出された場合は、インストールによって既存のインストールが上書きされるかどうかを、プロビジョニングソフトウェアが判別します。上書きされる場合、プロビジョニングソフトウェアは、既存のコンポーネントを依存先としている永続的な依存性をすべて検出し、インストールされる新しいコンポーネントについても依存性の制約が適合するかを検証し直します。適合しないものがある場合、新しいコンポーネントのインストールは失敗し、オリジナルコンポーネントがインストールされたままとなります。
すべて適合する場合、新しいコンポーネントがそのインストールを正常に完了した時点で、当該コンポーネントがすべての永続的な依存性の新しい依存先となります。オリジナルのコンポーネントはアンインストールされたと見なされ、そのコンポーネントの依存元であったすべての永続的な依存性が削除されます。つまり、新しいコンポーネントは必要に応じて依存性を作成し直す必要があります。
依存性の名前は、「 xxx2 yyy」という形式に従います。xxx は依存元コンポーネントの名前、 yyy は依存先コンポーネントの名前を示します。
たとえば、管理対象サーバー WebLogic はその管理サーバーに対して server2domain という依存性を持ち、その包含クラスタに対して server2cluster という依存性を持つ例が考えられます。この慣例は依存関係の状態を自己記録として表現するのに便利であり、特定のコンポーネントの依存先関係と依存元関係の両方を示すことができます。
このステップは、インストール中のコンポーネントの現在のインストール状態のスナップショットを作成します。インストールブロックには、任意の数の <createSnapshot> ステップを指定できます。
<createSnapshot> ステップは引数の引き渡しをサポートしないため、必要なパラメータを指定されたスナップショットブロックで宣言することはできません。引数の引き渡しがサポートされないのは、この機能をサポートすると生成されたスナップショットに対してあとで比較が行われる際に引数の収集と引き渡しのサポートも必要となるためです。
複合コンポーネントに対して行われる比較には、そのコンポーネントにより直接作成されるすべてのスナップショットが含まれます。またこのような比較には、入れ子になったすべてのコンポーネント参照の再帰的なインストールによって作成されたスナップショットのツリー一式も含まれます。しかし、最上位のコンポーネント参照に関連付けられたスナップショットは考慮されません。そのため、<addSnapshot> キャプチャ命令を使用して、複合コンポーネントのスナップショット内にそのようなスナップショットを明示的に含める必要があります。
また、入れ子になったコンポーネントは相互に依存していることがあり、このような場合にはそれらのコンポーネントがすべてインストールされるまでスナップショットのキャプチャを延期する必要があります。相互依存の関係にある例として、ディレクトリを配備する入れ子コンポーネントと、そのディレクトリにファイルを配備する入れ子コンポーネントが挙げられます。このような相互依存の場合、包含コンポーネントは、インストール中にスナップショットを作成しないように入れ子コンポーネントに指示するパラメータの引渡し、または特殊なインストールブロックを使用して、入れ子コンポーネントをインストールする必要があります。その後、<addSnapshot> 命令を使用して、包含コンポーネントのスナップショットブロックに、入れ子コンポーネントの適切なスナップショットを含めるようにします。
<createSnapshot> ステップには entityName 型の 1 つの必須属性 blockName があり、これは当該コンポーネント内で実行するスナップショットブロックの名前です。
このステップは、ターゲットホストにコンポーネントをインストールします。このステップを使用すると、対象コンポーネントの指定されたインストールブロックのステップが実行されます。
このステップの構文は、コンポーネントターゲッターを省略できる (ターゲッターを省略すると <thisComponent> が指定されたと想定される) 点を除き、単純プラン <install> ステップ (「<install> ステップ」を参照) で指定する場合と同じです。
コンポーネント内で使用される場合、このステップは同一コンポーネント内のほかのインストールブロックの呼び出しに使用されます。この場合、一番外側のインストールブロックがその実行を完了するまで、コンポーネントのインストールが完了したとは見なされません。また、ほかのローカルインストールブロックの呼び出し対象がほかのホストに変更された場合でも、コンポーネントは最初のインストールステップの対象となったホストにインストールされたとしか見なされません。
このステップは、参照先コンポーネントをインストールする目的で複合コンポーネント内でも使用できます。参照先コンポーネントは、包含コンポーネントのインストール先以外のホストにもインストールできます。包含コンポーネントのインストールが失敗する場合、この失敗以前にインストールが正常に行われている入れ子になった参照先コンポーネントはすべて、アンインストールブロックを実行することなく暗黙にアンインストールされます。しかし、失敗以前にインストールが正常に行われた最上位の参照先コンポーネントはインストールされたままとなります。
このステップは、包含コンポーネントのリソースを配備します。このステップは、単純コンポーネントのインストールブロックでのみ使用可能です。属性または子要素はありません。
deployMode=ADD_TO であるディレクトリ型リソースは、それが包含している各ファイルをコピーし、ディレクトリ構造を維持します。また、必要に応じて新しいディレクトリが作成されます。既存のディレクトリの構造とコンテンツは (リソースコンテンツのコピーを除き) 変化しません。 個々のファイルアクセス許可と所有権は、適宜更新されます。
deployMode=REPLACE であるディレクトリ型リソースは、配備前に既存ディレクトリが再帰的に削除されることを除き、deployMode=ADD_TO と同様に扱われます。
ほかのリソースはすべてコピーされ、続いてアクセス許可と所有権が適宜更新されます。構成可能としてチェックインされたリソースには、コピーされる前に変数置換が行われます。 構成可能リソースは、リソースが宣言されているコンポーネントにアクセス可能な任意の変数を参照できます。
この節では、コンポーネントのアンインストールブロック内でだけ使用できる、<uninstall> ステップと <undeployResource> ステップを説明します。
このステップは、ターゲットホストからコンポーネントをアンインストールするために使用され、任意のコンポーネントのアンインストールブロックで使用できます。このステップを使用することで、対象コンポーネントの指定されたアンインストールブロックのステップが実行されます。
このステップの構文は、コンポーネントターゲッターを省略できる (ターゲッターを省略すると <thisComponent> が指定されたと想定される) 点を除き、単純プラン <uninstall> ステップで指定する場合と同じです。
コンポーネント内で使用される場合、このステップは同一コンポーネント内のほかの既存アンインストールブロックの呼び出しに使用されます。この場合、一番外側のアンインストールブロックがその実行を完了するまで、コンポーネントはアンインストールされません。また、ほかのローカルアンインストールブロックの呼び出し対象がほかのホストに変更された場合でも、コンポーネントは当初アンインストールステップの対象となったホストでのみアンインストールされます。
このステップは、参照先コンポーネントをアンインストールする目的で、複合コンポーネント内でも使用できます。 複合コンポーネントがアンインストールされる場合、入れ子になったその参照先コンポーネントのうち明示的にアンインストールされなかったものはすべて、アンインストールブロックを実行することなくシステムによって暗黙にアンインストールされます。しかし、明示的にアンインストールされなかった最上位の参照先コンポーネントはインストールされたままとなります。
このステップは、包含コンポーネントからリソースを削除するために使用されます。このステップは単純コンポーネントのアンインストールブロックでのみ使用可能で、また属性も子要素もありません。
deployMode=ADD_TO であるディレクトリ型リソースの場合、そのファイルは削除されますがサブディレクトリは残ります。
deployMode=REPLACE であるディレクトリ型リソースの場合、ディレクトリ全体とそのコンテンツが削除されます。
ほかのリソースはどれも単純ファイルとして扱われ、削除されます。
リソースは、当該コンポーネントのインストール時に初めから配備されたかどうかにかかわらず削除されます。つまり、<deployResource> ステップを含まないインストールブロックを使用して当該コンポーネントがインストールされた場合でも、<undeployResource> ステップによって、リソースはコンポーネントによって初めからインストールされていたかのように削除されます。