Java Desktop System Configuration Manager Release 1.1 開発者ガイド

付録 B 要素の辞書

この付録では、テンプレートで使用可能な要素と属性すべてのリファレンスを提供します。

ヘッダー要素 : apt:template、resImport、helpImport

<!ELEMENT apt:template (resImport*, category)>
<!ATTLIST apt:template
    xmlns:apt CDATA #FIXED "http://www.sun.com/jds/apoc/2004/template"
    xmlns:oor CDATA #FIXED "http://openoffice.org/2001/registry"
    xmlns:xs  CDATA #FIXED "http://www.w3.org/2001/XMLSchema"
    xmlns:xsi CDATA #FIXED "http://www.w3.org/2001/XMLSchema-instance"
>

<!ELEMENT resImport EMPTY><!ATTLIST resImport
    apt:packagePath NMTOKEN #REQUIRED
>

ルート要素テンプレートには 2 つのサブ要素 resImport と category があり、これらについては、「構造体要素 : カテゴリ、ページ、セクション」で説明しています。

resImport 要素はリソースファイルのインポートに使用します。インポートされたリソースバンドルのリソースキーは、すべてテンプレートに通知されます。リソースキーを使用するリソースを、たとえば apt:label 属性にインポートする必要があります。「構造体要素 : カテゴリ、ページ、セクション」を参照してください。apt:packagePath 属性は、パスを使用してリソースの場所を指定します。区切り文字はドット (.) です。ファイルの接尾辞 (.properties) は、ISO 言語コード (ISO-639) および ISO 国コード (ISO 3166) と同様に指定する必要がありません。パスのルートディレクトリは、package の下にある res ディレクトリです。「ローカライズ」も参照してください。

構造体要素 : カテゴリ、ページ、セクション

<!ELEMENT category (category | page)>
<!ATTLIST category
    apt:name ID #REQUIRED
    apt:scope (user | host | global) #IMPLIED
    apt:label NMTOKEN #IMPLIED
    apt:inlineHelp NMTOKEN #IMPLIED
>
<!ELEMENT page ((section | set)+, xmlHandler*)><!ATTLIST page
    apt:name ID #REQUIRED
    apt:scope (user | host | global) #IMPLIED
    apt:label NMTOKEN #IMPLIED
    apt:inlineHelp NMTOKEN #IMPLIED
    apt:onlineHelp CDATA #IMPLIED
>
<!ELEMENT section (property+)>
<!ATTLIST section
    apt:name ID #REQUIRED
    apt:scope (user | host | global) #IMPLIED
    apt:label NMTOKEN #IMPLIED
>

category 要素は、設定ポリシーツリーでページの一意な配置を定義するために使用します。その最初の属性は apt:name 属性です。name 属性は、要素の一意な名前を定義するために使用します。大きいテンプレートの方向付けと要素の参照を円滑にします。

category 要素の 2 番目の属性は apt:scope です。scope 属性は、設定オプションを適用できるツリーを指定します。スコープが "user" の場合は、組織ツリーのみに設定オプションが適用されます。スコープが "host" の場合は、ドメインリーのみに設定オプションが適用されます。スコープが "global" の場合は、両方のツリーに設定オプションが適用されます。デフォルト設定は "global" です。要素は、独自のスコープを定義する場合を除いて、親要素からスコープを継承します。要素のスコープが "user" で、ドメインツリーに接続している設定ポリシーツリーが「コンテンツ区画」に表示されている場合、その要素はユーザーに表示されません。要素のスコープが "host" で、組織ツリーに接続している設定ポリシーツリーが表示されている場合も、同様です。

category 要素の 3 番目の属性は apt:label です。label 属性は、ユーザーに表示可能な要素の名前を指定し、ローカライズをサポートしています。label 属性で指定される文字列は、最初にリソースバンドルで検索されます。文字列と一致するキーが見つかった場合は、その値が GUI に表示されます。どのリソースバンドルにも文字列と一致するキーがない場合は、その文字列が GUI に表示されます。label 属性を指定しなければ、name 属性で指定された文字列が GUI に表示されます。属性を両方とも定義しない場合は、出力が表示されません。

category 要素の 4 番目の属性は apt:inlineHelp です。inlineHelp 属性は、GUI に表示されるヘルプテキストを指定します。ヘルプはカテゴリ名の右にある「コメント」列に表示されます。前述の label 属性と同様に、ローカライズをサポートしています。

カテゴリ階層の終わりに 1 つだけページ要素があります。この要素はオプション 1 ページを表し、category 要素で認識される 4 つの属性 name、 scope、 label、inlineHelp が含まれています。inlineHelp 属性の値はページタイトルの下に表示されます。label 属性の値はページのタイトルとして表示されます。カテゴリ名とページ名は、設定ポリシーツリーでページの一意な場所と名前を定義します。

apt:onlineHelp 属性は、オンラインヘルプが含まれている HTML ファイルを Configuration Manager で使えるようにします。Configuration Manager のマストヘッドでユーザーが「ヘルプ」リンクをクリックしたときに、この要素が参照している HTML ページがコンテキスト依存ヘルプとして表示されます。 apt:filePath 属性は、パスを使用してヘルプファイルの場所を指定します。区切り文字はスラッシュ ("/") です。ファイルの接尾辞 (.html) は、ISO 言語コード (ISO-639) および ISO 国コード (ISO 3166) と同様に指定する必要がありません。パスのルートディレクトリは、 package ディレクトリの下にある web ディレクトリです。「ローカライズ」も参照してください。

ページには任意の数のセクションやセットを含めることができ、そのあとにオプションとして xmlHandlers のリストを付加することもできます。したがって、page 要素にはサブ要素の section、 set (「動的データ要素 : set」を参照) と xmlHandler (「対話要素 : xmlHandler、event、action、choose、command」を参照) が含まれます。

section 要素は、そのプロパティのサブ要素すべてをテーブルに似たレイアウトで視覚的にグループ化します。これには category 要素から認識される 3 つの属性 name、 scope、 label が含まれています。label 属性の値はセクションタイトルとして表示されます。

基本データ要素 : property、value、constraints

<!ELEMENT property (constraints?, value*, visual)>
<!ATTLIST property
    apt:name ID #REQUIRED
    apt:scope (user | host | global) #IMPLIED
    apt:label NMTOKEN #IMPLIED
    apt:inlineHelp NMTOKEN #IMPLIED
    apt:dataPath CDATA #REQUIRED
    oor:type (xs:boolean | xs:short | xs:int | xs:long | xs:double | 
              xs:string | xs:hexBinary |
              oor:any | oor:boolean-list | oor:short-list | oor:int-list | 
              oor:long-list | oor:double-list | oor:string-list | oor:hexBinary-list)
              #IMPLIED
    apt:storeDefault (true | false) #IMPLIED
    apt:xmlHandler IDREF #IMPLIED
    apt:extendsProperty CDATA #IMPLIED
>
<!ELEMENT visual (checkBox | chooser)?>
<!ATTLIST visual
 apt:type (textField | password | textArea | radioButtons | comboBox | stringList | 
           colorSelector | hidden) #IMPLIED
>

<!ELEMENT checkBox EMPTY>
<!ATTLIST checkBox
 apt:labelPost NMTOKEN #IMPLIED
>

<!ELEMENT chooser EMPTY>
<!ATTLIST chooser
 apt:labelPopup NMTOKEN #IMPLIED
 apt:listDataPath CDATA #IMPLIED
 apt:extendsChooser CDATA #IMPLIED
>
<!ELEMENT constraints (enumeration*, length?, minLength?, maxLength?, minInclusive?, 
                       maxInclusive?, minExclusive?, maxExclusive?)>
<!ELEMENT enumeration EMPTY>
<!ATTLIST enumeration 
    oor:value CDATA #REQUIRED
    apt:label NMTOKEN #IMPLIED
>
<!ELEMENT value (#PCDATA)>
<!ATTLIST value
    xsi:nil (true | false) #IMPLIED
    oor:separator CDATA #IMPLIED
>

property 要素は、チェックボックス、ラジオボタン、編集フィールドなどの GUI 要素を通して設定オプションを視覚化します。これには、category 要素で認識される 4 つの属性 name、 scope、 label、inlineHelp が含まれています。インラインヘルプは、「値」列の入力フィールドの下に (または値文字列の下に編集不可の形で) 表示されます。label 属性の値は GUI 要素のラベルとして表示されます。カテゴリ名、ページ名、セクション名、プロパティ名は、設定ポリシーツリーでページの一意な場所と名前を定義します。

属性 apt:dataPath は、プロパティの値を保存するデータのバックエンドの場所を指すパスを定義します。dataPath 属性の値は、コンポーネントの絶対パス (たとえば org.openoffice.Office.Common/ExternalMailer/Program) です。付録 A 「設定パスのマッピング」を参照してください。property 要素の dataPath 属性は、データのバックエンドプロパティを指す必要があります。データのバックエンドノードを指すと、実行時エラーが発生します。

apt:type は、リポジトリの設定データの種類を指定するために使用します。次のタイプが定義されます。

xs:boolean	ブール値 (true/false)
xs:short	16 ビットの整数
xs:int	32 ビットの整数
xs:long	64 ビットの整数
xs:double	浮動小数点数 (IEEE 64 ビット double の値範囲)
xs:string	プレーンテキスト (印刷可能な Unicode 文字のシーケンス)
xs:hexBinary	未解釈オクテットのシーケンス、16 進数エンコード
oor:any	上記すべてのタイプを含む
oor:*-list	上記いずれかのタイプのリスト

以上のタイプは StarSuite/OpenOffice.org Registry (OOR) 形式で定義されているタイプに似ています。再利用できるように、APOC テンプレートでは可能な限り OOR 形式の構文を使用しています。タイプの詳細は、 http://util.openoffice.org/common/configuration/oor-document-format.html で OpenOffice.org Registry Format (OOR) に関する文書を参照してください。

属性 apt:storeDefault は、デフォルトデータをデータのバックエンドに保存するようConfiguration Manager に指示します。デフォルトデータは value 要素によって定義され (以下を参照)、ユーザーにデフォルトを表示するために使用します。ユーザーが値を変更しない場合や、「コンテンツ区画」で「デフォルトの適用」アクションを実行してデフォルトデータの保存を明示的に要求した場合は、デフォルトデータがリポジトリに保存されません。storeDefault 属性の値を true に設定すると、ユーザーが値を変更しない場合や「デフォルトの適用」を実行した場合でも、デフォルトデータが保存されます。

property 要素には 3 つのサブ要素 constraints、 value、visual があります。

visual 要素は、GUI のプロパティの表示タイプを定義します。表示タイプには、checkBox、 radioButtons、comboBox、stringList、 textField、password、textArea、chooser、 colorSelector、hidden があります。GUI の各要素には、編集と編集不可の 2 種類の表示形態があります。編集不可の表示形態は、Configuration Manager を使用している管理者がそのプロパティに書き込み権限を持たない場合に描画されます。表示タイプの形態については、次の表を参照してください。

表示タイプ	編集可能の表示形態	編集不可の表示形態
`textField`
`password`
`textArea`
`checkBox`
`radioButtons`
`comboBox`
`chooser`
`stringList`
`colorSelector`

hidden プロパティは、視覚的な GUI 要素を描画しませんが、プロパティに関連付けられた値をブラウザの非表示フィールドに渡します。この機能は、たとえばフロントエンドで入力された 1 つの値をバックエンドの複数の場所で保存しなければならない場合に便利です。

表示タイプは apt:visual 要素のtype 属性によって定義されます。ただし、checkBox と chooser は例外です。これら 2 つの GUI 要素を正しく表示するには追加情報が必要なので、これらの要素にはその情報を含める独自のサブ要素があります。

checkbox プロパティはチェックボックスの前後に文字列を表示します。これは checkBox 要素で表します。checkBox GUI 要素を編集不可の形態 (上の表を参照) で表示するには、さらに 2 つ文字列が必要になります。したがって、checkBox GUI 要素には 4 つ文字列が必要で、次のように表示されます。

チェックボックスの前。この文字列はproperty 要素の label 属性で定義される
チェックボックスの後。この文字列は checkBox サブ要素の apt:labelPost 属性で定義される。この属性を定義しなければ、label 属性で定義された文字列に「.post」が付加される。この文字列はリソースファイルでキーとして検索される
チェック付きのチェックボックスではなく、チェックボックスが編集不可の表示形態の場合。文字列は constraints 要素の最初の enumeration サブ要素の label 属性で定義される。制約を指定しなければ、 property 要素 label 属性で定義された文字列に接尾辞「.checked」が付加される。この文字列はリソースファイルでキーとして検索される
チェックなしのチェックボックスではなく、チェックボックスが編集不可の表示形態の場合。文字列は constraints 要素の最初の enumeration サブ要素の label 属性で定義される。制約を指定しない場合は、 property 要素 label 属性で定義された文字列に接尾辞「.unchecked」が付加される。この文字列はリソースファイルでキーとして検索される

chooser プロパティを使用すると、エントリのリストの値が確定されます。これは chooser 要素で表します。コンボボックスと違って、エントリのリストは編集可能です。このリストは apt:chooser 要素のdataPath 属性で指定したバックエンドの場所に保存されます。

「編集」ボタンをクリックすると、ポップアップウィンドウが開き、リストを編集するための GUI が提供されます。ポップアップウィンドウの内容のタイトルは、apt: chooser 要素の labelPopup 属性で定義します。constraints 要素の enumeration サブ要素を使用すると、リストのデフォルト値を指定できます (下の制約に関する説明を参照)。

chooser 要素の apt:extendsChooser プロパティは、別の chooser 要素を参照するために使用します。このプロパティを使用すると、以前に定義した chooser 要素を簡単に再利用できます。その参照先 chooser で定義されている要素と属性のすべてが、参照元 chooser で定義されているかのように解釈されます。参照元 chooser で定義されているサブ要素と属性が、参照先 chooser の要素や属性を上書きします。プロパティのパスは、参照先 chooser の検索に使用されます。プロパティのパスは、ルートカテゴリからプロパティまでのパスの全要素の apt:name の値をスラッシュ ("/") で区切って連ねたものです。たとえば、次のように入力します。/StarSuite/Internet/Proxy/Settings/MyChooser

表示タイプが指定されていない場合は、type 属性から GUI 要素が引き出されます。タイプが xs:booleanの場合は、チェックボックスが使用されます。タイプがリストの種類 (たとえば oor:short-list) 、 xs:hexBinary、または oor:any の場合は、テキスト領域が表示されます。その他のタイプの場合は、編集フィールドが使用されます。表示タイプもデータ型も指定されていない場合は、編集フィールドが表示され、バックエンドのデータ型が xs:string であると想定されます。

constraints 要素は入力フィールドに制約を加えます。たとえば、ユーザーが保存できる値を 1 から 5 までの整数に限定する場合は、oor:type 属性を「xs:int」と一緒に提供するだけでは不十分です。minInclusive 制約 1 と maxInclusive 制約 5 を指定して、必要な制約を与えます。

checkbox プロパティと一緒に使用する場合は、列挙制約にもう 1 つの用途があります。最初の enumeration constraints サブ要素は、チェックボックスがオンになっている場合にバックエンドに保存する値を定義し、2 番目の enumeration constraints サブ要素は、チェックボックスがオフになっている場合にバックエンドに保存する値を定義します。制約を指定しなければ、保存されるデフォルト値は true と false です。編集不可の表示形態で GUI に表示されるデフォルトの文字列は、「使用する」と「使用しない」です。

列挙制約は、radiobutton プロパティと combobox プロパティの場合は必須である以外は、意味が checkbox プロパティと同じです。これらの要素の内容は開発者が自由に決めることができます。GUI に表示される名前は、constraint 要素の label 属性で定義します。列挙制約では label 属性の省略が可能です。その場合は、property 要素の label 属性で定義した文字列に接尾辞を付加して追加のリソースを指定します。

たとえば、プロパティのラベルが「securityList」で、列挙制約に「1」、「2」、「3」の値が含まれていても列挙制約のラベルが定義されていないドリップダウンボックスがあるとします。ユーザーに表示される文字列は、リソースキーの「securityList.1」、「securityList.2」、「securityList.3」のそれぞれを検索して決定されます。

chooser プロパティのリストエントリはローカライズされません。その結果、列挙制約の apt:label 属性はこれらのプロパティには影響しません。

その他の制約については、OpenOffice.org Registry Format (OOR) の文書の Property Constraints を参照してください。

value 要素には、プロパティのデフォルト値が含まれています。このデフォルト値は、デフォルト階層に含まれている値と同じにするか、ここで新たに指定することができます。これは、データのバックエンドにデータが見つからない場合に、Configuration Manager が表示する値を定義します。

value 要素の定義は、OOR 形式で与えられる定義と似ています。 value 要素にはサブ要素がなく、nil、 separator、 lang という 3 つの属性があります。xsi:nil 属性を true に設定すると、プロパティの値が「値なし」として定義されます。oor:separator 属性は、value 要素にリスト型の値が含まれている場合に、リストトークンの区切り文字として使う文字列を指定するために使用します。

ヒント –

stringList プロパティのリストエントリは、oor:string-list 型の値として保存されます。デフォルトの区切り文字はセミコロン (;) です。

apt:xmlHandler 属性については、「対話要素 : xmlHandler、event、action、choose、command」を参照してください。

動的データ要素 : set

<!ELEMENT set (page)>
<!ATTLIST set
    apt:name ID #REQUIRED
    apt:scope (user | host | global) #IMPLIED
    apt:label NMTOKEN #IMPLIED
    apt:labelPopup NMTOKEN #IMPLIED
    apt:dataPath CDATA #REQUIRED
    apt:elementNamePath CDATA #IMPLIED
>

これまでに紹介した要素はすべて、バックエンドの静的コンテンツを処理しました。set 要素は、動的コンテンツを処理するために使用します。これは section 要素のようにページのサブ要素で、プロパティのセットをテーブルに表示します。

これには、 category 要素で認識される 3 つの属性 name、 scope、 label が含まれています。label 属性の値はテーブルのタイトルとして表示されます。

apt:dataPath 属性は、要素のセットを含んだデータのバックエンドノードを指すパスを定義します。dataPath 属性の値は、 org.openoffice.Office.Commands/Execute/Disabled 形式の絶対パスです (付録 A 「設定パスのマッピング」を参照)。 set 要素の dataPath 属性は、バックエンドのノードを指す必要があります。バックエンドのプロパティを指すと、エラーが発生します。

セットの子孫の dataPath 属性には動的な部分が含まれている必要があります。この動的な部分は、セットのメンバーであるバックエンドのノードの場所を指定します。バックエンドのセットのメンバーにアクセスするためには、名前が異なる必要があります。これを実現するには、変数が使用されます。

変数にはドル記号の接頭辞 $variable_name が付きます。有効な変数名は queriedId と silentId です。$queriedId 変数を指定した場合は、ユーザーに一意の ID を問い合わせる追加の編集フィールドが表示されます。 $silentId 変数を指定した場合は、ユーザーに ID を問い合わせずに、Configuration Manager で自動的に一意な ID が生成されます。

たとえば、property 要素の dataPath 属性の値が org.openoffice.Office.Commands/Execute/Disabled/$queriedId/Command であるとします。ユーザーが新しいセット要素を作成した場合は、セットメンバーの名前も要求されます。GUI に表示される実際の質問の文字列は apt:labelPopup 属性で指定します。この属性を省略した場合は、「新しい項目の名前を入力してください」 というプロンプトが表示されます。

パスの文字列の長さを最小限にするには、セットまたはプロパティの dataPath 属性の値として相対パスを指定することも可能です。相対パスの例は ./$queriedId/Command です。絶対パスは、テンプレート要素ツリーを上に移動し、相対パスにその祖先の dataPaths の接頭辞を付けて構成します。たとえば、プロパティの親がセットであるとします。このセットは dataPath の値 org.openoffice.Office.Commands/Execute/Disabled を指定します。Configuration Manager は、このパスに相対パス ./$queriedId/Command を結合して絶対パス org.openoffice.Office.Commands/Execute/Disabled/$queriedId/Command を生成します。

dataPath 属性 (set 要素と property 要素) をサポートしているセットのすべての子孫がその dataPath 属性の値として絶対パスを指定している場合は、セットの dataPath 属性を指定する必要はありません。

再帰的なセットの構造 (セットのセット) も処理できます。これは、セット要素に page 要素を含め、それにまた set 要素を含めることで実現します。サブセットの dataPath 属性では、スーパーセットに相対するパスを指定できます。

セットのメンバーがバックエンドプロパティの場合、バックエンドプロパティの oor: name 属性は、GUI でラベルとして表示されます。バックエンドプロパティの値は GUI 要素のラベルとして表示されます。

セットのメンバーがバックエンドのノードの場合は、バックエンドノードの oor:name 属性は、リンクの名前として表示されます。apt:elementNamePath 属性を使用すると、この命名スキームを上書きできます。elementNamePath は、バックエンドのノードに相対するパスを指定します。このパスは、バックエンドのプロパティを指している必要があり、その値はリンクの名前として表示されます。このようなリンクをユーザーがクリックすると、「コンテンツ区画」が更新されて、セットの page サブ要素で指定されたページが表示されます。

対話要素 : xmlHandler、event、action、choose、command

<!ELEMENT xmlHandler (event+, action+)>
<!ATTLIST xmlHandler apt:name ID #REQUIRED>

<!ELEMENT event EMPTY>
<!ATTLIST event apt:type (onChange) #IMPLIED>

<!ELEMENT action (choose|command)+>

<!ELEMENT choose (when+, otherwise?)>

<!ELEMENT when (command+)>
<!ATTLIST when apt:test CDATA #REQUIRED>

<!ELEMENT otherwise (command+)>

<!ELEMENT command (#PCDATA)>

xmlHandler 要素は、クライアント側で JavaScript コードを実行する場合に使用します。コードの実行は、環境の変化によってトリガされます。このような変化はイベントで伝播されます。イベントは、状態が変わった場合にプロパティによって発行されます。イベントタイプは変化の種類を示します。

XML ハンドラを定義するには、apt:template 要素のxmlHandler サブ要素の指定します。これは、 apt:name 属性で定義した名前が必要になります。XML ハンドラは、property 要素の apt:xmlHandler 属性を指定 (XML ハンドラの名前をその値として使用) して、プロパティが発行したイベントを待機するように登録されます。

event 要素は、 xmlHandler が待機するイベントを、その apt:type 属性を使用して指定する場合に使用します。ここでは、onChange 要素のみを定義します。このイベントは、ユーザーがその値を変更した場合にプロパティによって発行されます。プロパティの値は、たとえば、ユーザーが編集フィールドでキーを入力したり、チェックボックスをオフにしたり、リストボックスでエントリを選択してこの入力を変更した瞬間に変化します。GUI 要素にフォーカスを移したり、GUI 要素からフォーカスを外しても、このイベントはトリガされません。

1 つまたは複数のプロパティでイベントのハンドラが登録され、これらのプロパティのいずれかでそのイベントが発生した場合に、action 要素で定義されているコードが実行されます。action 要素には、 choose 要素か command 要素が少なくとも 1 つ含まれています。

command 要素は、クライアント側で実行される命令を指定します。現時点で含めることができるのは代入式のみです。代入式の左辺および右辺でも計算は許可されていません。代入式のスキーマは次のとおりです。<variable>=<value>

ドット表記 <property>. <qualifier> のあとには変数が続きます。<property> はプロパティの名前です。<qualifier> には、“value” と “enabled” の 2 つの値が可能です。value 修飾子はそのプロパティの値を提供します。変数の値は、プロパティで指定されているタイプと互換性がある限り、読み取ってどの値にでも確定できます。enabled 修飾子には、プロパティが有効になっている (フォーカスを受け取れる) 場合は「true」が含まれ、そうでない場合は「false」が含まれます。これを読み取って「true」または「false」に設定できます。例 : propname.enabled=false

choose 要素は XSLT で定義される choose 要素に似ており、コマンドを条件付きで実行できます。when 要素を少なくとも 1 つ含んでいる必要があり、末尾に otherwise 要素を 1 つ含むことができます。

when 要素には、 1 つまたは複数の command サブ要素と 1 つの apt:test 属性があります。test 属性では、ブール値に評価される式を指定する必要があります。

式は、変数、数字、文字列、および以下のトークンで構成できます。

=	等しい
!=	等しくない
<	より小さい
>	より大きい
<=	以下
>=	以上
( )	挿入要素
not()	ブール演算子 NOT
and	ブール演算子 AND
or	ブール演算子 OR
true	ブール肯定
false	ブール否定

例 : (propname.enabled!=false) and not(propname.value='foo')

式が「true」に評価される場合は、when 要素のコマンドが実行され、choose ステートメントが実行されます。「false」に評価される場合は、次の when 要素が評価されます。どの when 要素も true ではなく、otherwise 要素が指定されている場合は、otherwise 要素のコマンドが実行されます。