javax.microedition.rms
クラス RecordStore

java.lang.Object
  javax.microedition.rms.RecordStore

public class RecordStore
extends Object

レコード・ストアを表すクラスです。 レコード・ストアは MIDlet アプリケーションの複数の呼び出しを超えて内容が持続しつづけるレコードの集合体です。 プラットフォームは、MIDlet のリブート、バッテリーの変更などを含むプラットフォームの正常な使用の範囲において、レコード・ストアを完全に維持するように最大限の努力をします。

レコード・ストアは MIDlet アプリケーションに露出していない、プラットフォーム依存の場所に作成されます。 レコード・ストアの名前空間は、MIDlet スイート (suite) 単位でコントロールされます。 個々の異なる名前を与える限り、MIDlet スイート内の各 MIDlet は複数のレコード・ストアを作成することができます。 MIDlet スイートがプラットフォームから削除される際には、その各 MIDlet に関連する全てのレコード・ストアも削除されます。 レコード・ストアを操作する API は MIDlet スイートに対応するレコード・ストアの操作のみを許可し、異なる MIDlet スイートの各 MIDlet 間のレコードを共有するメカニズムは提供しません。 MIDlet スイート内の各 MIDlet はお互いのレコード・ストアに直接アクセスすることができます。

レコード・ストアの名前はケース・センシティブ（大文字小文字等を同一視しない）な 32 個の Unicode 文字による任意の構成を使用することができます。 レコード・ストアの名前はその MIDlet スイート内において、ユニークでなければなりません。 言い換えれば、MIDlet スイート内の各 MIDlet は同じ名前のレコード・ストアを複数作成することはできません。 しかし、異なる MIDlet スイート間においては同じ名前のレコード・ストアを作成することができます。 その場合、同名の各レコード・ストアは別個に扱われます。

この API はいかなるロックオペレーションも提供しません。 レコード・ストアの実装は、各レコード・ストアに対する全てのオペレーションが、１単位（atom）であること、同期化が行われること（synchronous）、操作順に適用されること（serialized）を保証します。 従って、欠落は複数の接続間で起こることはありません。 しかし、レコード・ストアにアクセスするために、MIDlet アプリケーションが複数のスレッドを使用するならば、その調整は MIDlet アプリケーション側で行わなければなりません。 これを行わなかった場合、意図していない結果を生じることがあります。 同様に、プラットフォームがレコード・ストアの透過的な同期を実行する場合、プラットフォームの責任において MIDlet アプリケーションと同期化エンジンとの間のレコード・ストアに対する排他的なアクセスを実施しなければなりません。

レコードはそれぞれに割り当てられるレコード ID（これは int 値である）によって、レコード・ストア内でユニークに識別されます。 このレコード ID はレコードのために主キーとして使用します。 レコード・ストア内で作成された最初のレコードのレコード ID は 1 となります。 レコード・ストアに後から加えられた個々のレコードはその前に加えられたレコードのレコード ID よりも 1 大きな値が割り当てられます。 すなわち、２つのレコードがレコード・ストアに加えられ、１番目のレコードのレコード ID が n である場合、次のレコードのレコード ID は n + 1 となります。 各 MIDlet は RecordEnumeration インタフェースの使用により、他の索引を作成することができます。

このレコード・ストアは System.currentTimeMillis() メソッドによって返される日時情報を表す long 型の値を使用します。 レコード・ストアは前回内容が修正された時刻を記録するためにこの値を使用します。 また、レコード・ストアはバージョンを保持しています。 バージョンはレコード・ストアの内容を変更する操作のたびにインクリメントされる整数です。 これらは、同期エンジンで使用する際にも役立ちます。

openRecordStore

public static RecordStore openRecordStore(String recordStoreName,
                                          boolean createIfNecessary)
                                   throws RecordStoreException,
                                          RecordStoreFullException,
                                          RecordStoreNotFoundException

MIDlet スイートに関連するレコード・ストアをオープンあるいは作成します。 レコード・ストアが MIDlet スイートによって既に開かれている場合、このメソッドは同じ RecordStore オブジェクトへの参照を返します。

パラメータ:

recordStoreName - MIDlet スイート内においてユニークな 32 文字以内のレコード・ストアの名前を渡します。

createIfNecessary - 必要に応じて新しいレコード・ストアを作成する場合は true を、作成しない場合は false を渡します。

戻り値:

このレコード・ストアの RecordStore オブジェクトを返します。

例外:

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

RecordStoreNotFoundException - 対応するレコード・ストアが存在しない場合に throw します。

RecordStoreFullException - レコード・ストアに空き容量がなく操作を完了できない場合に throw します。

listRecordStores

public static String[] listRecordStores()

MIDlet スイートが持つ、全てのレコード・ストアの名前を文字列配列で返します。 MIDlet スイートがレコード・ストアを所有していない場合、このメソッドは null を返すことに注意が必要です。

レコード・ストアの名前が格納される順序は実装に依存します。

戻り値:

MIDlet スイートが所有しているレコード・ストアの名前を格納した文字列配列あるいは null を返します。

deleteRecordStore

public static void deleteRecordStore(String recordStoreName)
                              throws RecordStoreException,
                                     RecordStoreNotFoundException

指定された名前のレコード・ストアを削除します。 MIDlet スイートは自分自身が所有するレコード・ストアのみを削除することができます。 このメソッドが呼び出された際に、該当するレコード・ストアが MIDlet アプリケーションによって開かれている場合は RecordStoreException を throw します。 また指定された名前のレコード・ストアが存在しない場合には RecordStoreNotFoundException を throw します。

パラメータ:

recordStoreName - MIDlet スイートが所有している削除する対象のレコード・ストアの名前を渡します。

例外:

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

RecordStoreNotFoundException - 対応するレコード・ストアが存在しない場合に throw します。

addRecord

public int addRecord(byte[] data,
                     int offset,
                     int numBytes)
              throws RecordStoreNotOpenException,
                     RecordStoreException,
                     RecordStoreFullException

レコード・ストアに新しいレコードを加えます。 この新しいレコードのためのレコード ID を返します。 これはブロックを伴う分割不可能な操作です。 このメソッドから処理が戻る前に、そのレコードは内容を保持するストレージに書き込まれます。

パラメータ:

data - このレコードに格納するデータを渡します。なお、numBytes が 0 の場合、null を渡すことができます。

offset - data の示す配列中のデータを開始する位置を渡します。

numBytes - このレコードへ格納するデータのバイト数を渡します。0 を指定することもできます。

戻り値:

新しいレコードのレコード ID を返します。

例外:

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

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

RecordStoreFullException - レコード・ストアに空き容量がなく操作を完了できない場合に throw します。

deleteRecord

public void deleteRecord(int recordId)
                  throws RecordStoreNotOpenException,
                         InvalidRecordIDException,
                         RecordStoreException

レコード ID に対応するレコードをレコード・ストアから削除します。 そのレコードのためのレコード ID が再使用されることはありません。

パラメータ:

recordId - 削除対象のレコードのレコード ID を渡します。

例外:

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

InvalidRecordIDException - レコード ID が不適切な場合に throw します。

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

closeRecordStore

public void closeRecordStore()
                      throws RecordStoreNotOpenException,
                             RecordStoreException

MIDlet アプリケーションがレコード・ストアのクローズを要求する場合にこのメソッドを呼び出します。 openRecordStore(java.lang.String, boolean) メソッドを呼び出してオープンした回数このメソッドを呼び出すまで、実際にはレコード・ストアがクローズされないことに注意が必要です。 言い換えれば、MIDlet アプリケーションはレコード・ストアをオープンする呼び出しと同じ回数のクローズする処理を作成することを必要とされています。

レコード・ストアがクローズされる際、登録されているリスナーは全て削除されます。 クローズされた RecordStore オブジェクトに対して操作の実行を MIDlet アプリケーションが行おうとした場合、メソッドは RecordStoreNotOpenException を throw します。

例外:

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

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

getRecordSize

public int getRecordSize(int recordId)
                  throws RecordStoreNotOpenException,
                         InvalidRecordIDException,
                         RecordStoreException

指定された MIDlet スイートが所有するレコードのサイズをバイト単位で返します。

パラメータ:

recordId - 対象のレコードに対応するレコード ID を渡します。

戻り値:

対象レコードのサイズをバイト単位で返します。

例外:

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

InvalidRecordIDException - レコード ID が不適切な場合に throw します。

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

getRecord

public int getRecord(int recordId,
                     byte[] buffer,
                     int offset)
              throws RecordStoreNotOpenException,
                     InvalidRecordIDException,
                     RecordStoreException

指定されたレコードに格納されているデータを返します。

パラメータ:

recordId - 対象のレコードに対応するレコード ID を渡します。

buffer - データをコピーする先の byte 配列を渡します。

offset - データのコピーを開始する buffer 内の位置を渡します。

戻り値:

位置 offset から始まる、buffer へコピーしたデータのバイト数を返します。

例外:

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

InvalidRecordIDException - レコード ID が不適切な場合に throw します。

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

ArrayIndexOutOfBoundsException - レコードが buffer に格納しきれない場合に throw します。

getRecord

public byte[] getRecord(int recordId)
                 throws RecordStoreNotOpenException,
                        InvalidRecordIDException,
                        RecordStoreException

指定されたレコードに格納されているデータを返します。

パラメータ:

recordId - 対象のレコードに対応するレコード ID を渡します。

戻り値:

レコードの内容をコピーした byte 配列を返します。レコードにデータが格納されていない場合、null を返すことに注意が必要です。

例外:

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

InvalidRecordIDException - レコード ID が不適切な場合に throw します。

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

setRecord

public void setRecord(int recordId,
                      byte[] newData,
                      int offset,
                      int numBytes)
               throws RecordStoreNotOpenException,
                      InvalidRecordIDException,
                      RecordStoreException,
                      RecordStoreFullException

指定されたレコードに渡されたデータを格納します。 このメソッドの実行後、getRecord(recordId) を呼び出すと、numBytes サイズのデータを格納して返します。

パラメータ:

recordId - 対象のレコードに対応するレコード ID を渡します。

newData - 新しくレコードに格納するデータを渡します。

offset - 格納するデータを取り出す newData 内の位置を渡します。

numBytes - レコードへ格納する newData 内のデータのバイト数を渡します。

例外:

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

InvalidRecordIDException - レコード ID が不適切な場合に throw します。

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

RecordStoreFullException - レコード・ストアに空き容量がなく操作を完了できない場合に throw します。

getName

public String getName()
               throws RecordStoreNotOpenException

この RecordStore の名前を返します。

戻り値:

この RecordStore の名前を返します。

例外:

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

getVersion

public int getVersion()
               throws RecordStoreNotOpenException

レコード・ストアが変更、追加、削除された際にインクリメントされるバージョンを返します。 各 MIDlet アプリケーションは、高速に何かが変更されたか否かを判定するためにこれを使用することができます。 バージョン番号の初期値は実装に依存する、0 以上の正数です。 RecordStore が更新されると共に、バージョン番号はインクリメントされます。

戻り値:

レコード・ストアの現在のバージョンを返します。

例外:

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

getNumRecords

public int getNumRecords()
                  throws RecordStoreNotOpenException

レコード・ストアに含まれる現在のレコード数を返します。

戻り値:

レコード・ストアに含まれる現在のレコード数を返します。

例外:

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

getSize

public int getSize()
            throws RecordStoreNotOpenException

レコード・ストアが使用しているスペースの量をバイト単位で返します。 返すサイズには、レコード・ストアなどの状態を管理するために使用される管理領域のような実装に関連した全てのオーバーヘッダを含んでいます。

戻り値:

レコード・ストアが使用しているバイト数を返します。

例外:

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

getSizeAvailable

public int getSizeAvailable()
                     throws RecordStoreNotOpenException

このレコード・ストアが利用可能な追加的なサイズをバイト単位で返します。 実装がネイティブアプリケーション、同期などを備えたインテグレーションをサポートするために各レコードの追加データ構造体を格納するため、これが必ずしも格納することができる MIDlet アプリケーションにおける、追加的なデータ量ではないことに注意が必要です。

戻り値:

このレコード・ストアが利用可能な追加的なサイズがバイト単位で返します。

例外:

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

getLastModified

public long getLastModified()
                     throws RecordStoreNotOpenException

このレコード・ストアが最後に更新された日時を System.currentTimeMillis() によって使用されているフォーマットで返します。

戻り値:

このレコード・ストアが最後に更新された日時を System.currentTimeMillis() によって使用されているフォーマットで返します。

例外:

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

addRecordListener

public void addRecordListener(RecordListener listener)

指定されたレコードリスナーを追加します。 指定されたリスナーが既に登録されている場合は、初回以後の登録時には追加を行いません。 レコード・ストアがクローズされる際にリスナーは全て削除されます。

パラメータ:

listener - 登録するリスナーオブジェクトを渡します。

関連項目:

removeRecordListener(javax.microedition.rms.RecordListener)

removeRecordListener

public void removeRecordListener(RecordListener listener)

指定されたレコードリスナーを削除します。 指定されたリスナーが登録されていないければ、このメソッドは何も処理を行いません。

パラメータ:

listener - 削除するリスナーオブジェクトを渡します。

関連項目:

addRecordListener(javax.microedition.rms.RecordListener)

getNextRecordID

public int getNextRecordID()
                    throws RecordStoreNotOpenException,
                           RecordStoreException

次にレコード・ストアへ加えるレコードのレコード ID を返します。 これは擬似リレーショナル関係を構築するのに役立てることができます。 すなわち、そのレコードがお互いを参照する必要のある２つレコード・ストアが存在知る場合に、別のレコード・ストアにレコードを格納する前に、一方のレコード・ストアの中に追加されるレコードのレコード ID を先行して決定することができます。 レコード・ストアがオープン状態を保つ間か addRecord(byte[], int, int) を呼び出すまで、このメソッドが返すレコード ID が有効であることに注意が必要です。

戻り値:

次にこのレコード・ストアに追加されるレコードのレコード ID を返します。

例外:

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

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

enumerateRecords

public RecordEnumeration enumerateRecords(RecordFilter filter,
                                          RecordComparator comparator,
                                          boolean keepUpdated)
                                   throws RecordStoreNotOpenException

レコードセット内の１セットのレコードを指定した順に自由に移動することができる列挙を返します。

もしも filter が null でなければ、レコード・ストア内のレコードをどのようにサブセット化するか決定するために使用します。 また、もしも comparator が null でなければ、返すレコードを並べる順番を決定するために使用します。

filter および comparator の両方が null の場合、列挙は順不同にレコード・ストア内の全てのレコードを自由に移動することができます。 これはレコード・ストアに含まれる全てのレコードを自由に移動するもっとも効率的な方法です。

最初の RecordEnumeration.nextRecord() の呼び出しは、順序の先頭にあるレコードからデータを返します。 次の RecordEnumeration.nextRecord() の呼び出しは、連続する次のレコードのデータを返します。 現在の位置から前方に連続しているレコードからデータを返すためには RecordEnumeration.previousRecord() を呼び出します。 一方で最初の呼び出しが RecordEnumeration.previousRecord() の場合、列挙の最後に位置するレコードからデータを返します。 個々の RecordEnumeration.previousRecord() の呼び出しはシーケンスを通して前へ（後方から先頭へ向かって）進みます。

keepUpdated に true を指定すると常に最新の状態を維持します。 全ての変更において RecordEnumeration を維持することにより、性能的な問題が発生する可能性があります。 このため、この設定は慎重に行わなければなりません。

false を指定した場合、RecordEnumeration は直ちに現状を反映せず、削除されたレコードあるいは後で追加されたレコードを対象としないレコード ID を返すことが許されます。 また、RecordEnumeration 構築後に修正された結果、フィルタの対象外となるレコードも返します。

パラメータ:

filter - レコードセットからレコードのサブセットを使用するためのフィルタあるいは null を渡します。

comparator - レコードを返すための順番を決定するコンパレータあるいは null を渡します。

keepUpdated - レコード・ストアの変更と RecordEnumeration による内容を一致させる場合は true を、そうでなければ false を渡します。

戻り値:

レコードセット内の指定したレコードのセットが指定した順番に並べられた自由に移動することができる列挙を返します。

例外:

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

関連項目:

RecordEnumeration.rebuild()