Basic Functionality of the Class RecordStore
Record stores are represented in the RMS API by the class RecordStore. The RecordStore class provides methods to open, close, read, and manipulate the record store. It also provides access to meta-information such as the number of records and the memory space still available and currently consumed.
Global Record Store Methods and Exceptions
An instance of the RecordStore class, representing a single record store, can be obtained via the static method openRecordStore(). The method call requires two parameters: the name of the RecordStore and a flag specifying whether the RecordStore should be created if it does not exist yet. The name of the record store should be a String consisting of no more than 32 Unicode characters. The names are case sensitive, so Foo, foo, and FOO would denote different record stores. The following line opens the record store named myRecords and creates it if it does not exist yet:
RecordStore myRecords = RecordStore.openRecordStore("myRecords", true);
Other general static methods are provided for listing all record stores of a MIDlet suite and deleting a record store. Because these methods are static, it is possible to use them without obtaining an instance of RecordStore first. These general methods are listed in Table 5.1. To use all other RecordStore access methods, you must create a RecordStore instance by calling openRecordStore().
Note
MIDP 2.0 introduces two additional openRecordStore() methods to share
RecordStores across multiple MIDlet suites. An additional setMode() method allows you to change the access mode of a RecordStore later.
The first new openRecordStore() method requires four parameters. The first two parameters are identical to the existing openRecordStore() method and define the name of the record store and whether the store should be created as if it does not yet exist. The third parameter defines the access mode. The constant RecordStore.AUTHMODE_PRIVATE indicates that only MIDlets in the same MIDlet suite can access the RecordStore. RecordStore.AUTHMODE_ANY enables any MIDlet to access the RecordStore. The fourth parameter is a boolean specifying whether the RecordStore is writable by other MIDlet suites in the AUTHMODE_ANY case.
The second new openRecordStore() method takes only three String parameters. Again, the first parameter defines the name of the RecordStore. The second and third parameter define a vendor and a MIDlet suite name required to get access to the RecordStore.
The authentication mode of a record store can be changed after creation using the setMode() method. This method takes the previously described authentication mode and the write flag as parameters.
All three methods can throw a SecurityException if the desired operation is not permitted.
For closing a record store, the API provides the method closeRecordStore(). At the latest, any open record store owned by an application should be closed when the application is terminated. Please note that the number of calls to close a certain record store must match the calls to openRecordStore(). Calling closeRecordStore() allows the system to free resources associated with a record store.
| Method Name | Purpose |
|---|---|
| String[] listRecordStores() | Returns all record stores in a String array that are available in the current MIDlet suite. |
| RecordStore openRecordStore (String recordStoreName, boolean createIfNecessary) | Opens a record store. |
| void deleteRecordStore (String recordStoreName) | Deletes a complete record store from the MIDlet suite. |
The RecordStore methods can throw different types of Exceptions in case of a failure. The exceptions are listed in Table 5.2. For example, a RecordStoreNotFoundException is thrown if the desired record store does not exist in the MIDlet suite and the openRecordStore() method is called without setting the create option. In case of success, the method returns an instance of the RecordStore class.
Manipulating Single Records
When the record store is successfully opened, you can add new records using the addRecord() method. This method takes three parameters. The first is the byte array containing the data that should be written to the record store. The second specifies the offset from which to start writing data of the byte array. The third specifies how many bytes of the given array should be written. The method returns the index of the newly created record. Like all RecordStore methods, addRecord() may throw different types of RecordStoreExceptions in case of a failure. If you want to write the complete byte array, set the second parameter to 0 and the third to the length of the byte array:
myRecords.addRecord (myBytes, 0, myBytes.length);
For replacing a record at a given index, RecordStore provides the method setRecord(). The usage of the setRecord() method is similar to addRecord(), except that the index of the record to be replaced must be given as the first parameter. In contrast to addRecord(), no index value is returned. Please note that the first record in a record store has the index number 1, and not 0 as in most other Java APIs dealing with indexed structures. Specifying a record ID of 0 or any other invalid record ID will result in an InvalidRecordIDException. The following call replaces the first record of a record store with the complete byte array given as the second parameter:
myRecords.setRecord (1, myBytes, 0, myBytes.length);
For reading records, RMS provides two different getRecord() methods. The simple version of getRecord() takes a record ID as a parameter and returns a byte array containing the corresponding record data. Using the following line of code, you can read the data of the first record in the myRecords record store:
byte[] recordData = myRecords.getRecord (1);
The second variant of getRecord() avoids allocating a new byte array by writing data to a byte array given by the application. It is invoked with more parameters and provides a different return value. As with the simple version, the first parameter is the record ID. The second parameter is a byte array that is used for storing the data read. The third parameter is the offset at which to start writing the record data in the given byte array. As a result, the method returns the number of bytes transferred to the specified buffer. The application is required to provide a buffer that is large enough to store the record with the given ID. If the buffer size is not sufficient, an ArrayIndexOutOfBoundException is thrown. The following lines allocate a byte array as a buffer and read the first record from the myRecords record store into the newly allocated buffer:
byte[] myBuffer = new byte [BIG_ENOUGH]; int numberOfBytesRead = myRecords.getRecord (1, myBuffer, 0);
Records that are no longer needed can be deleted using the deleteRecord() method. The only parameter of deleteRecord() is the ID of the record to be deleted. After deletion, the record is removed from the RecordStore irrevocably. Please note that the record ID of the removed record is not reused and cannot be reset with a new record using the setRecord() method. In case of resetting a previously deleted record, an InvalidRecordStoreIDException is thrown. All further records keep their record IDs.
Meta Information
In addition to methods manipulating whole record stores or single records, the RMS API also provides a set of methods for obtaining information about a record store or single records.
All methods to get record store meta information are listed in Table 5.3. One important method needed, for example, to iterate all records in a record store is getNumRecords(). This method is invoked on a record store instance and returns the number of records stored in the record store as an integer value. The following line shows how the method is called to get the number of records in the myRecords record store:
int numberOfRecords = myRecords.getNumRecords ();