コレクション
Content Engine コレクションとは、関連するエレメントのグループで、List 型と Set 型の 2 つがあります。コレクションの名前により、型が識別できます。例えば DocumentSet オブジェクトは Document オブジェクトのコレクションで、IdList オブジェクトは Id オブジェクトのコレクションです。
Content Engine API コレクション・オブジェクトはすべて、厳密に型指定されています。API から戻るときに、これらの型を認識するコレクション・オブジェクトには、コレクションのオブジェクト型に直接関連するオブジェクト型のエレメントのみが格納されます。例えば、Java™ の Folder.get_ContainedDocuments メソッドまたは .NET IFolder.ContainedDocuments プロパティーから返される DocumentSet コレクション・オブジェクトには、指定されたフォルダー内に含まれている Document オブジェクト (およびそのドキュメントからサブクラス化されたオブジェクト) のみが含まれます。
EngineCollection インターフェースは、コレクション・クラス階層内のすべてのコレクション型の基本インターフェースであり、すべてのコレクション・オブジェクトに共通の機能を提供します。そのサブインターフェースである EngineSet には、Set にのみ適用される機能が用意されています。すなわち、List 型コレクションには EngineCollection で提供されるすべての機能がありますが、EngineSet の機能はありません。一方、Set 型コレクションには、EngineCollection と EngineSet のすべての機能があります。
List 型コレクションは、依存オブジェクトのグループ、またはプリミティブ型のデータ・アイテムのリストです。List 型コレクションには、そのスコープとなる親オブジェクトがあります。List 型のコレクション・オブジェクトは、その型に特有の Factory クラスの createList メソッドを使用してインスタンス化されます。例えば、IdList のインスタンスを作成するには、Factory.IdList.createList を呼び出します。リストのエレメントは順序付きであり、固有である必要はありません。List 型コレクションでは、一度に 1 つのエレメントに対して反復処理ができます。タイプ・セーフなメソッドを使用して、List 型コレクションを直接更新できます (エレメントの追加、削除など)。
Set 型コレクションは、独立オブジェクトのグループです。以下の例外を除き、セットのエレメントは順序なしで、固有です。
- ComponentRelationship オブジェクトには、セット内のアイテムをソートする ComponentSortOrder プロパティーがあります。
- ChildDocument オブジェクトおよび ChildRelationship オブジェクトから返されたセットは、サーバーによって、確実にアイテムがソート順序にソートされて返されます。ドキュメントが再使用される場合、同じ ChildDocument オブジェクトがコレクション内の複数の場所に存在することがあります。
Set 型コレクションを直接更新することはできません。Set 型コレクションでは、ページングできます。すなわち、一度に 1 ページに対して反復処理ができます。ページングの詳細情報については、コレクションのページング・サポートと、Java の PageIterator インターフェースと PageMark インターフェースまたは .NET の IPageEnumerator インターフェースと IPageMark インターフェースを参照してください。行集合は、照会から返される行のコレクションで、Set 型コレクションの特性があります。詳細については、RepositoryRowSet インターフェースを参照してください。
コレクションのページング・サポート
Content Engine API では、Set 型コレクションに対して、従来の「アイテム単位」での反復処理に加えて、ページングがサポートされます。サーバーからクライアントに送信された列挙型の結果については、ページングが自動的に使用されます。カスタム・アプリケーションでもページングを使用できます。例えば、ユーザー・インターフェース上に表示されるアイテムの概算数に合わせてページ・サイズを指定するように、アプリケーションを記述することもできます。取得したページごとに、結果の次のページを取得している間に表示します。
ページングの動作方法
独立オブジェクトおよびリポジトリー行のセットは、サーバーから物理的に取得されるときに、ページに分割されます。各ページは、コレクション・エレメントのサブセットを表すいくつかのコレクション・エレメント (オブジェクトまたは行) です。一度に 1 つのオブジェクトまたは 1 行を反復処理する代わりに、1 ページを反復処理できます。例えば、1 ページが 10 エレメントとして定義されたときに、コレクションに合計 22 個のエレメントがある場合、最初のページング操作により 10 個のエレメントが含まれるページが返され、2 ページ目に次の 10 個のエレメント、さらに 3 ページ目に残りの 2 個のエレメントが返されます。ページ反復処理は API によって開示されていて、情報をページ単位で開示する対話型のアプリケーションで特に有用です。
各ページ・イテレーターは、初期状態では、セットの最初のページの前に配置されています。PageIterator.nextPage メソッドの最初の呼び出しにより、イテレーターは最初のページに移動します。nextPage の 2 回目の呼び出しにより、イテレーターは 2 ページ目に移動し、以降同様に動作します。セットの末尾に到達するまで、nextPage メソッドは true を返します。イテレーターは、セットの末尾に到達すると最終ページの後に配置され、nextPage が false を返します。
イテレーターが、最初のページの前または最終ページの後に配置されている場合、あるいは reset(mark) 操作の後でページ間に配置されている場合、getCurrentPage メソッドおよび getElementCount メソッドは例外を発行します。新規のイテレーターまたはリセット操作後のイテレーターの配置を正しくするには、nextPage を呼び出す必要があります。getPageMark メソッドは、いつ呼び出してもかまいません。これらのメソッドのうち、イテレーターの位置を移動するのは nextPage のみです。
getElementCount の戻り値は常に getCurrentPage().length と等しくなります。大容量である可能性がある内部配列のコピーを回避するため、単に長さを取得する場合には getElementCount を使用してください。
現在のページの継続状態 (イテレーターの次の呼び出しの起点ページ) を取得すること、およびイテレーターを 1 つ前の結果ページに戻すことも可能です。イテレーターの保存位置は「ページ・マーク」と呼ばれ、PageMark オブジェクトで表されます。PageIterator.getPageMark メソッドは現在のマークを取得し、reset(mark) メソッドは前に保存したマークにイテレーターの状態を戻します。reset メソッドはマークされたページの前にイテレーターを配置します。マークされたページにイテレーターを配置するには、nextPage メソッドを呼び出す必要があります。最初のページの前および最終ページの後をマークして、その位置に戻すこともできます。
reset メソッド (パラメーターなし) の呼び出しは、イテレーターをコレクションの最初のページの前に配置します。これは、コレクションから新しいイテレーターを取得するのと実質的に同じです。次に nextPage メソッドを呼び出して、イテレーターを最初のページに配置する必要があります。
getPageSize メソッドおよび setPageSize メソッドを使用すると、イテレーターの内部ページング・サイズに対して照会を実行し、それを調整できます。新しいサイズは、サーバーから次にページをフェッチするとき (通常は、nextPage に対する次の呼び出し) に有効になります。返される各ページの実際のサイズは、要求したページ・サイズよりも短い (0 を含む) ことも長いこともあります。これらの呼び出しでページ・サイズを指定しない場合、構成されているデフォルト値が使用されます。照会結果およびページングしたプロパティー値のページ・サイズのデフォルト値は、ServerCacheConfiguration.QueryPageDefaultSize プロパティーで指定されます。このプロパティーを明示的にほかの値に設定しない場合、デフォルト値は 500 です。ページ・サイズを指定する場合、その値は、QueryPageMaxSize プロパティーに設定されている構成済みの最大ページ・サイズ (システムのデフォルト値は 1000) より小さくする必要があります。
クライアントのページング要求を処理するステートレスな中間層ソフトウェアの場合、PageIterator には getCurrentPageCheckpoint メソッドと getNextPageCheckpoint メソッドがあります。これらのメソッドは、後で Factory.PageIterator.resumeInstance を使用して再開するためのチェックポイントとして機能する、PageIterator メソッドの不透明 (opaque) 型の表現を返します。
セットの最初のページを、サーバーからプリフェッチし、クライアントにキャッシュできます。最初のページをプリフェッチ済みのセットのイテレーターはすべて同じ最初のページを返す可能性があります。いずれのイテレーターも、以降のページはサーバーから直接フェッチします (ある場合)。
コレクション全体をページングする方法について詳しくは、「コレクションの操作」を参照してください。