javax.microedition.rms
インタフェース RecordEnumeration

public interface RecordEnumeration

レコード・ストアの中のレコードを双方向に移動可能な RecordEnumeration を定義するインタフェースです。 RecordEnumeration は、理論上レコード・ストア内のレコードのレコード ID の順序を維持します。 この RecordEnumeration は、レコードの全て（あるいは、もしもオプションの RecordFilter が指定されている場合はそれに含まれるレコード）を、オプションの RecordComparator によって決定された順序に従って列挙します。

オプションの RecordFilter を使用することにより、レコード全体から設定したフィルタの条件に適合するレコードのみを列挙することができます。 これは条件によるサーチ機能を提供するために使用することができます。

オプションの RecordComparator を使用することにより、コンパレータによって決定された順序にレコードを通してアクセスすることができます。 これはソート機能を提供するために使用することができます。

RecordEnumeration にレコードが列挙された後に、レコードが RecordStore から削除された場合、レコード ID は有効なレコードを示さない可能性があります。 この問題を回避するために、RecordEnumeration はオプションで RecordStore のリスナーとなり、レコードの追加と削除に対応して内部のインデックスを再構築することができます。 しかし、このオプションを使用すると、全てのレコードの追加、変更および削除時にインデックスの再構築を行うため、実行時のパフォーマンスに対して重大な影響を与えることがあるため、特に注意が必要です。

この RecordEnumeration によって使用される RecordStore が閉じられるなら、この RecordEnumeration は無効になり、それに実行された後続の全ての作業は、後に同じ RecordStore が開かれたとしても、無効の結果となるか、または RecordStoreNotOpenException を thorw します。 さらに、hasNextElement() および hasPreviousElement() の呼び出しは false を返します。

最初の nextRecord() の呼び出しは、シーケンスの最初のレコードからレコード・データを返します。 次の nextRecord() の呼び出しは、次の連続するレコードのデータを返します。 列挙されたレコードの現在のポイントから１つ前のレコード・データを取得する場合には previousRecord() を呼び出します。 最初の呼び出しが previousRecord() の場合、列挙の最後の要素をレコード・データとして返します。 個々の previousRecord() の呼び出しはシーケンスを通して前へ（後方から先頭へ向かって）進みます。

レコード・ストアを検索するためには、希望のサーチ条件を持つ RecordFilter を備え、RecordComparator を持たない RecordEnumeration を作成します。

導入されたバージョン:

MIDP 1.0

numRecords

int numRecords()

この RecordEnumeration が保持している利用可能なレコード数を返します。 すなわち、保持しているレコード数はフィルタ基準と一致します。 このメソッドの呼び出しが、全てのレコード（レコード・ストアに多くのレコードがある場合、無視できない処理時間がかかるかもしれません）にフィルタを適用することにより、完全な列挙を構築することを RecordEnumeration に要求することに注意が必要です。

戻り値:

RecordEnumeration が保持している利用可能なレコード数を返します。 すなわち、フィルタ評価基準に一致するレコードの数です。

nextRecord

byte[] nextRecord()
                  throws InvalidRecordIDException,
                         RecordStoreNotOpenException,
                         RecordStoreException

この RecordEnumeration の生成時に設定されたフィルタおよびコンパレータにより定義された、次のレコードのコピーを返します。 返す byte 配列はレコードのコピーです。 この配列の内容を変更しても、レコード・ストアには反映しません。 このメソッドの呼び出し後の RecordEnumeration は使用可能な次のレコードを指します。

戻り値:

この RecordEnumeration 内の次のレコード・データを返します。

例外:

InvalidRecordIDException - これ以上、使用可能なレコードがない場合に throw します。

RecordStoreNotOpenException - レコード・ストアがオープンされていない場合に throw します。

RecordStoreException - 一般的なレコード・ストアに関する例外が発生した場合に throw します。

nextRecordId

int nextRecordId()
                 throws InvalidRecordIDException

この RecordEnumeration の生成時に設定されたフィルタおよびコンパレータにより定義された、次のレコードのレコード ID を返します。 このメソッドの呼び出し後の RecordEnumeration は使用可能な次のレコードを指します。

戻り値:

この RecordEnumeration の次のレコード ID を返します。

例外:

InvalidRecordIDException - これ以上、使用可能なレコードがない場合に throw します。 このメソッドのその後の呼び出しは、reset() メソッドが列挙をリセットするために呼び出されるまで、この例外を投げ続けます。

previousRecord

byte[] previousRecord()
                      throws InvalidRecordIDException,
                             RecordStoreNotOpenException,
                             RecordStoreException

この RecordEnumeration の生成時に設定されたフィルタおよびコンパレータにより定義された、前のレコードのコピーを返します。 返された byte 配列はレコードのコピーです。 この配列の内容を変更しても、レコード・ストアには反映しません。 このメソッドの呼び出し後の RecordEnumeration は使用可能な前のレコードを指します。

戻り値:

この RecordEnumeration 内の前のレコード・データを返します。

例外:

InvalidRecordIDException - これ以上、使用可能なレコードがない場合に throw します。 このメソッドのその後の呼び出しは、reset() メソッドが列挙をリセットするために呼び出されるまで、この例外を投げ続けます。

RecordStoreNotOpenException - レコード・ストアがオープンされていない場合に throw します。

RecordStoreException - 一般的なレコード・ストアに関する例外が発生した場合に throw します。

previousRecordId

int previousRecordId()
                     throws InvalidRecordIDException

この RecordEnumeration の生成時に設定されたフィルタおよびコンパレータにより定義された、前のレコードのレコード ID を返します。 このメソッドの呼び出し後の RecordEnumeration は使用可能な前のレコードを指します。

戻り値:

この RecordEnumeration の前のレコード ID を返します。

例外:

InvalidRecordIDException - これ以上、使用可能なレコードがない場合に throw します。 このメソッドのその後の呼び出しは、reset() メソッドが列挙をリセットするために呼び出されるまで、この例外を投げ続けます。

hasNextElement

boolean hasNextElement()

さらに次のの要素が存在するか否かを判定します。

戻り値:

存在する場合は true を、存在しない場合は false を返します。

hasPreviousElement

boolean hasPreviousElement()

さらに前のの要素が存在するか否かを判定します。

戻り値:

存在する場合は true を、存在しない場合は false を返します。

reset

void reset()

この RecordEnumeration の位置を開始位置へ戻します。

rebuild

void rebuild()

現在のレコード・セットの内容をこの RecordEnumeration に反映するようにリクエストします。 MIDlet アプリケーションがレコードに多くの変更を行い、その新しい内容を RecordEnumeration へ反映する場合に有効なメソッドです。

関連項目:

keepUpdated(boolean)

keepUpdated

void keepUpdated(boolean keepUpdated)

この RecordEnumeration を構成するための内部インデックスをレコード・ストアに対して追加/削除/変更時に常に最新に保つか否かを設定します。 これはあらゆる変化において列挙を維持するために、関連する潜在的な性能問題のために慎重に使用すべきであることに注意が必要です。

パラメータ:

keepUpdated - true を指定すると、現在のレコード・ストアのレコードにおける全ての変化を列挙に反映させます。 性能的な問題が発生する可能性があるため、慎重に使用する必要があります。 keepUpdated(true) を呼び出すことは rebuild() を呼び出すのと同じ効果があります： 最新のレコード・セットを反映するために列挙を更新します。 もしも false を渡すなら、列挙は直ちには現状を反映せず、削除されたレコードおよび後に追加されたレコード ID を返すことがあります。 また、列挙の構築後にそれが変更された結果、対象外のレコードを返すことがあります。 レコードが後に直接あるいは列挙を通じて検索されると、レコード・ストアのレコードへの全ての変化が正確に反映されることに注意が必要です。 レコードが変更されるか、加えられるか、または削除されるとき、このパラメータに false を設定することによって危険に晒されるのは、フィルタリングおよび列挙の順序をソートすることです。

関連項目:

rebuild()

isKeptUpdated

boolean isKeptUpdated()

この RecordEnumeration がレコード・ストアの現在の内容を変更に合わせて反映するか否かを返します。

戻り値:

レコード・ストアの現在の内容を変更に合わせて反映する場合は true を、そうでなければ false を返します。

destroy

void destroy()

この RecordEnumeration によって使用している内部リソースを解放します。 RecordEnumeration を使用して、その使用を終了する際、MIDlet アプリケーションはこのメソッドを呼ぶべきです。 このメソッドが呼ばれた後の RecordEnumeration を MIDlet アプリケーションが使用しようとする場合、IllegalStateException を throw します。 このメソッドは、この列挙が既に必要ではないときに即座にリソース要求の最小化をマニュアルで補佐するために使用されることに注意が必要です。