バイナリー・ファイル は、Java File オブジェクトとして表されるオペレーティング・システム・ファイルです。
ODA でバイナリー・ファイル・コンテンツを生成するには、その ODA クラスに IGeneratesBinFiles インターフェースを実装する必要があります。 表 45 は、IGeneratesBinFiles インターフェースを実装する際に ODA クラスに定義する必要のあるメソッドを示しています。
表 45. IGeneratesBinFiles インターフェース内のメソッド
メソッド | IGeneratesBinFiles メソッド | 説明 |
---|---|---|
ソース・ノード生成メソッド |
なし
| ソース・ノードは、IGeneratesBoDefs インターフェースの getTreeNodes() メソッドで生成する必要があります。詳しくは、ファイルの使用を参照してください。 |
コンテンツ生成メソッド | generateBinFiles() | バイナリー・ファイルを生成し、それを ODA メモリーに書き込みます。 |
コンテンツ取得メソッド | getBinFile() | 指定したバイナリー・ファイル、またはすべてのバイナリー・ファイルを ODA メモリーから取得します。 |
ビジネス・オブジェクト・ウィザードは、「ビジネス・オブジェクトの生成中」ダイアログ・ボックス (ステップ 5) を表示して、コンテンツを生成および取得します。IGeneratesBinFiles インターフェースを実装している場合、ビジネス・オブジェクト・ウィザードは、表 46 に示すメソッドを呼び出して、コンテンツを生成および取得します。
表 46. ビジネス・オブジェクト・ウィザードと IGeneratesBinFiles メソッド
メソッドの用途 | IGeneratesBinFiles メソッド | 詳細情報の参照先 |
---|---|---|
ファイルをコンテンツとして生成します。 | generateBinFiles() | ファイルの生成 |
生成されたファイルを取得します。 | getBinFile() | 生成済みファイルへのアクセスの提供 |
以降のセクションでは、表 46 に示す各メソッドの実装について説明します。
IGeneratesBinFiles インターフェースを実装すると、ODA は、次の状況でオペレーティング・システム・ファイルの使用をサポートできるようになります。
ODA に IGeneratesBinFiles インターフェースを実装すると、ファイルをコンテンツとして作成することが可能となります。ODA が作成するファイルには、ビジネス・オブジェクト定義の生成プロセスやその他のプロセスから ODA が収集した情報が保持されます。ユーザーが選択したソース・ノードの配列 (ビジネス・オブジェクト・ウィザードがステップ 3「ソースの選択」の結果として作成するもの) がファイル生成プロセスで必要になった場合、ODA は、ビジネス・オブジェクト・ウィザードからこの配列を受け取ることができます。ファイルを生成するメソッドの実装方法については、ファイルの生成を参照してください。
ただし、ソース・ノードを検出し、ビジネス・オブジェクト・ウィザードにより「ソースの選択」ダイアログ・ボックスで表示されるツリー・ノードの配列を生成するソース・ノード生成メソッドは、IGeneratesBinFiles インターフェースには定義されていません。 ODA がファイル・コンテンツの生成をサポートし、ユーザーが選択したソース・ノードの配列がこのファイル生成で必要な場合、ODA は、IGeneratesBoDefs インターフェース内のソース・ノード生成メソッドである getTreeNodes() を使用する必要があります。
このメソッドは、指定した親ノードの子ノードについてデータ・ソースを照会し、関連するツリー・ノードを作成します (ソース・ノードの生成を参照)。
ODA で新しいファイルの作成 (ファイル生成) のみ をサポートする場合は、IGeneratesBoDefs に定義されている getTreeNodes() メソッドを使用することができます。このメソッドは、指定した親ノードの子ノードについてデータ・ソースを照会し、関連するツリー・ノードを作成します (ソース・ノードの生成を参照)。
IGeneratesBinFiles インターフェースを実装すると、ODA は、ソース・ノードに関連付けられたオペレーティング・システム・ファイルの読み取りをサポートできるようになります (ファイルをノードに関連付ける方法については、オペレーティング・システム・ファイルの関連付けを参照してください)。
ODA が読み取るファイルには、ソース・データが含まれています。ODA は、ソース・ノードとして表されるオブジェクトを、このソース・データから検索する必要があります。ファイルとノードの関連付けをサポートするために、ODA は次のステップを実行する必要があります。
詳しくは、ファイル・タイプ・ノードを参照してください。
重要 |
---|
指定されたオペレーティング・システム・ファイルを getClientFile() メソッドで正常に取得するには、ODA に IGeneratesBinFiles インターフェースを実装する必要があります。 ODA に IGeneratesBoDefs インターフェースしか実装していない場合、getClientFile() は UnsupportedContentException 例外をスローします。 |
getClientFile() メソッドの引き数には、取得するファイルのソース・ノード・パスを指定します。このソース・ノード・パスは、次のような形式で指定します。
fileNodePath:filePath
ここで、fileNodePath は関連するファイルを持つノードのノード・パス (ノード名はコロン (:) コロンで区切られている)、filePath は関連するファイルのオペレーティング・システム・パスです。関連するファイルであるノードを展開または選択すると、ビジネス・オブジェクト・ウィザードはそのノードに対してこのパスを作成します。
例えば、サンプル Roman Army ODA の ArmyAgent5 クラスは、IGeneratesBinFiles インターフェース、およびファイルとノードの関連付けの両方をサポートします。 図 49 に示すように、ユーザーが (C:¥IBM¥XMLFiles ディレクトリー内の) Flavius.xml ファイルを Vulso ソース・ノードに関連付けるものと仮定しましょう。ソース・ノード階層から Flavius.xml ノード (図 50 を参照) を選択すると、ビジネス・オブジェクト・ウィザードはソース・ノードの配列に次のノード・パスを組み込みます。
Apollo:Vulso:Flavius.xml:C:¥IBM¥XMLFiles¥Flavius.xml
この ODA は、ソース・ノード・パスの構文を解析する findSon() メソッドを提供し、ソース・ノードが表す関連オブジェクトを特定します。 ArmyAgent3 クラスの findSon() メソッドは、指定したソース・ノードに関連付けられているオブジェクトについて、ODA のデータ・ソース (RomanArmy.xml と呼ばれる XML ファイル) のみを照会します。ArmyAgent4 クラスの修正版のメソッドは、remoteSon() メソッドを提供することにより、関連ファイルを照会する機能を追加しています。remoteSon() メソッドは、指定されたファイルのコンテンツを getClientFile() を使用して取得し、そのコンテンツを Son オブジェクトととして戻します。
ソース・ノードとファイルとの関連付けが可能な場合は、ファイルのソース・ノード・パスを解釈し、そのファイルのコンテンツを読み取る機能が、コンテンツ生成時に必要となります。コンテンツを生成するメソッドは、ファイル内に存在するノードに格納された情報にアクセスできなければなりません。ノードに関連付けられているオペレーティング・システム・ファイルを getClientFile() を使用して取得するように、コンテンツを生成するメソッドを実装します。このサポートを提供するメソッドは、次のとおりです。
getClientFile() メソッドは、ビジネス・オブジェクト定義を作成するために必要な情報を generateBoDefs() で取得できるように、指定されたファイルのコンテンツを提供します。 ODA のデータ・ソースからのソース・ノード情報を取得するように generateBoDefs() メソッドがすでに実装されている場合は、関連ファイルからの情報も取得できるようにそれを拡張する必要があります。
コールバック生成の場合は、ユーザー定義メソッドがファイルを生成します。いずれの場合も、指定したファイルのコンテンツは getClientFile() メソッドが提供し、これによりメソッドは、ファイル生成に必要な情報を取得できるようになります。
ファイル・コンテンツの生成方法については、ファイルの生成を参照してください。
ユーザーが「ノードを選択」ダイアログ・ボックスでソース・ノードを選択すると、ODA は、コンテンツ生成を開始する準備が整います。ファイル生成プロセスの目標は、ODA またはその他のプロセスが必要とするファイルを 1 つ以上作成することです。ファイル生成を開始するステップは、ファイル・コンテンツ・タイプ (ContentType.BinaryFile) に関連付けられているコンテンツ・プロトコルによって異なります。
このセクションでは、ファイルを生成する際に generateBinFiles() メソッドで実行する必要のある次のステップについて説明します。
generateBinFiles() メソッドは、IGeneratesBinFiles インターフェース内で定義されています。したがって、IGeneratesBinFiles インターフェースを実装するときは、(ODKAgentBase2 から派生した) ODA クラスにこのメソッドを実装する必要があります。
generateBinFiles() メソッドの目的は、ファイル (ContentType.BinaryFile) コンテンツの生成用に ODA が使用するコンテンツ・プロトコルによって以下のように異なります。
ODA がファイルを「要求時」に生成する場合、ビジネス・オブジェクト・ウィザードは generateBinFiles() メソッドを明示的に呼び出してファイルの生成を開始します。したがって、generateBinFiles() は、ファイル・オブジェクトの生成を処理し、それを生成済みコンテンツ構造体に保管し、コンテンツ・メタデータをビジネス・オブジェクト・ウィザードに戻すように実装する必要があります。
generateBinFiles() メソッドの実行中、ビジネス・オブジェクト・ウィザードは「ビジネス・オブジェクトの生成中」画面 (ステップ 5) を表示します。最後のステップとして、generateBinFiles() は、生成されたファイルを記述するコンテンツ・メタデータ (ContentMetaData) オブジェクトを戻します (これには実際に生成されたファイルは含まれません)。
ODA がファイルをコールバックにより生成する場合、ビジネス・オブジェクト・ウィザードは generateBinFiles() メソッドを明示的に呼び出しません。代わりに、ODA はその他の方法を使用して「自発的に」ファイルを生成します。開発者は、ファイルの生成を処理し、それを生成済みコンテンツ構造体に保管して、コンテンツ生成が完了した旨をビジネス・オブジェクト・ウィザードに通知するようなメソッドを開発する必要があります。ただし、IGeneratesBinFiles インターフェースでは、generateBinFiles() メソッドを定義する必要があります。したがって、呼び出してはならないことを呼び出し側に警告するように generateBinFiles() を実装する必要があります。
サンプル Roman Army ODA は、ファイル生成用のコールバック・コンテンツ・プロトコルをサポートします (図 58 を参照)。これは、ArmyAgent5 クラス内に generateBinDefs() メソッドを定義しています。このメソッドの実装には、図 69 に示すコードが含まれます。このコードは、呼び出された場合に例外をスローするように generateBinFiles() メソッドを定義しています。
図 69. generateBinFiles() メソッドの定義
public ContentMetaData generateBinFiles(String[] nodes) throws ODKException { throw new ODKException( "Files are produced as callbacks. Do not call for file generation."); }
例外をスローする代わりに、generateBinFiles() メソッドは、contentUnavailable() メソッド (ContentMetaData で定義) を使用して、そのコンテンツ・メタデータをビジネス・オブジェクト・ウィザードに戻すことができます。
return (ContentMetaData.contentUnavailable(ContentType.BinaryFile));
ファイル生成プロセスの間に ODA で追加情報が必要となった場合は、「BO プロパティー」ダイアログ・ボックスが開くため、ユーザーはそこでビジネス・オブジェクト・プロパティーの値を入力することができます。
これらのプロパティーはビジネス・オブジェクト・プロパティーと呼ばれますが、getBOSpecificProps() メソッドを使用すれば、ファイル生成プロセスで必要とされる情報を表示することができます。
「BO プロパティー」ダイアログ・ボックスの使用方法については、ビジネス・オブジェクト・プロパティーの要求を参照してください。
ODK API では、バイナリー・ファイルを表す特別なクラスは提供されません。なぜなら、Java では java.io パッケージに File クラスがすでに用意されているからです。
このパッケージには、ファイルの生成やアクセスに役に立つ入出力クラスが多数含まれています。ODA は、生成する各ファイルごとに、次のステップを実行する必要があります。
ODA が実行する実際のファイル生成は、ODA の設計によって異なります。ODA の要件に最も適合するようにファイル生成を実装してください。また、ファイルを必要とするすべてのコンポーネントを実装してください。
サンプル Roman Army ODA の ArmyAgent5 クラスは、独立したクラス (FileCreator) を定義することにより、実際のファイル生成を処理します。「自発的な」ファイル生成をシミュレートする際に、このサンプルは、generateBoDefs() メソッドから FileCreator() コンストラクターを呼び出します (次のコード・フラグメントを参照)。
public ContentMetaData generateBoDefs(String[] nodes) throws ODKException { ContentMetaData cmd = super.generateBoDefs(nodes);
new FileCreator(this, nodes).start();
return cmd; }
FileCreator() コンストラクターは、ファイル生成用のスレッドを作成します。このコンストラクターは、現在の ODA オブジェクト (this) への参照と、選択したソース・ノードのノード・パスを持つ配列を、引き数として受け取ります。続いて、次のファイルを作成します。
生成済みコンテンツの提供で説明したように、ODA は生成済みコンテンツを 2 つの部分に分けてビジネス・オブジェクト・ウィザードに戻す必要があります。したがって、ODA がファイルをコンテンツとして生成する場合は、次のものを戻す必要があります。
この情報を提供するメソッドは、ファイル生成用に ODA が使用するコンテンツ・プロトコルによって異なります。
ODA がファイルを「要求時」に生成する場合、ビジネス・オブジェクト・ウィザードは generateBinFiles() メソッドを呼び出してファイル生成を処理します。したがって、generateBinFiles() は、生成済みコンテンツを次のように提供します。
ビジネス・オブジェクト・ウィザードは、このコンテンツ・メタデータ・オブジェクトを受け取ると、getBinFile() メソッドを必要に応じて使用することにより、(生成済みコンテンツ構造体内の) 生成済みファイルにアクセスできるようになります。
getBinFile() については、生成済みファイルへのアクセスの提供を参照してください。
ODA がファイルをコールバックにより生成する場合、ビジネス・オブジェクト・ウィザードは、ファイル生成を処理する際に generateBinFiles() メソッドを呼び出しません。代わりに、ODA はユーザー定義メソッドを使用して「自発的に」ファイルを生成します。このメソッドは、ODA クラスであっても、ODA パッケージ内のクラスであってもかまいません。ただし、このメソッドは、生成済みコンテンツを次のように提供する必要があります。
ファイルを生成するユーザー定義メソッドは、コンテンツ・メタデータを直接ビジネス・オブジェクト・ウィザードに戻すことはできません。なぜなら、ビジネス・オブジェクト・ウィザードはこのメソッドを呼び出していないからです。代わりに、このメソッドは、ODKUtility クラスで定義されている contentComplete() メソッドを呼び出すことにより、「コンテンツ生成が完了した」という旨のメッセージをビジネス・オブジェクト・ウィザードに送る必要があります。
このメソッドは、コンテンツ・メタデータ・オブジェクトを引き数として受け入れます。このコンテンツ・メタデータ・オブジェクトに含める必要のある情報については、表 47 を参照してください。このコンテンツ・メタデータは、ビジネス・オブジェクト・ウィザードに送られます。ビジネス・オブジェクト・ウィザードは、コンテンツ・メタデータ・オブジェクトを受け取ると、getBinFile() メソッドを使用して、(生成済みコンテンツ構造体内の) 生成済みファイルにアクセスできるようになります。
サンプル Roman Army ODA の ArmyAgent5 クラス内で、生成済みコンテンツ構造体は、m_files と呼ばれる File オブジェクトの配列として定義されています。
File[] m_files = null;
図 70 のコード・フラグメントは、ArmyAgent5.java ファイルに定義されている FileCreator.run() メソッドの最後の部分を示しています。
for (int i=0; i<fileV.size(); i++) m_agent.m_files[i] = (File) fileV.get(i); }
ODKUtility.getODKUtility.contentComplete( new ContentMetaData(ContentType.BinaryFile, 0, m_agent.m_files.length); } // end of run() in FileCreator class
図 70 のコード・フラグメントは、生成済みコンテンツを次のように処理します。
Roman Army サンプル ODA が m_files 配列を生成済みコンテンツ構造体として使用します。生成したファイルを保管する際は、run() がそのファイルをこの m_files 配列に保管します。このステップは、run() によってすべての ファイルが生成された後に実行されます。ビジネス・オブジェクト・ウィザードは、コンテンツ取得メソッド (getBinFile()) の呼び出しを通じて、m_files 配列にアクセスできます。
run() メソッドは、contentComplete() メソッドを呼び出して、新しい ContentMetaData オブジェクトを渡します。
run() は、表 47 に示す情報を ContentMetaData() コンストラクターに渡します。
ContentMetaData 情報 | コード | 説明 |
---|---|---|
コンテンツ・タイプ | ContentType.BinaryFile |
コンテンツ・タイプがファイルであることを示します。
|
生成済みコンテンツのサイズ | 0 |
合計サイズが必須でない ことを示します。現在の ContentMetaData オブジェクトの実装では、長さの値は必要ありません。
|
生成済みコンテンツの数 | m_files.length |
length メンバー変数には、現在配列内にある要素の数が含まれます。
|
generateBinFiles() メソッドは、実際に生成されたビジネス・オブジェクト定義を戻しません。ビジネス・オブジェクト・ウィザードで生成済みコンテンツにアクセスできるようにするには、ファイル用のコンテンツ取得メソッドを ODA クラスに実装する必要があります。ビジネス・オブジェクト・ウィザードは、generateBinFiles() によって戻される コンテンツ・メタデータ・オブジェクト内の情報を使用して、どのコンテンツ取得メソッドを呼び出すのかを決定します。ファイル・コンテンツの場合、ビジネス・オブジェクト・ウィザードは getBinFile() メソッドを呼び出して、生成済みのビジネス・オブジェクト定義を取得します。
ODA がファイル生成用のコールバック・コンテンツ・プロトコルをサポートしている場合、ファイルを実際に生成するのはユーザー定義メソッドです。
ただし、このメソッドは、実際に生成されたコンテンツは戻しません。したがって、ビジネス・オブジェクト・ウィザードは依然として、生成済みファイルにアクセスするために、getBinFile() メソッドを必要とします。
ファイル生成用に ODA でサポートされるコンテンツ・プロトコルとは無関係に、ODA クラスには getBinFile() メソッドを実装する必要があります。このメソッドは、IGeneratesBinFiles インターフェース内で定義されています。
このメソッドは、戻されるファイルの数を識別するインデックスを引き数として受け入れます。また、このメソッドは、生成済みコンテンツ構造体内のファイルにアクセスし、取得したファイル (File) オブジェクトの配列を戻します。この配列内のファイルの数は、表 48 に示すように、インデックス引き数の値によって異なります。
サンプル Roman Army ODA の場合、FileCreator.run() メソッド (ArmyAgent5 クラスで定義) は、m_files 配列に生成済みファイルを設定します。したがって、getBinFile() メソッド (これも ArmyAgent5 クラスで定義) は、指定した数のファイルをこの配列から取得します。次のコードは、サンプル Roman Army ODA の getBinFile() メソッドを示しています。
public File[] getBinFile(long index) throws ODKException { if (index == ODKConstant.GET_ALL_OBJECTS) return m_files; else return new File[] {m_files[(int)index]}; }