Managing RecordStores | ColdFusion MX Professional Projects

Team-Fly

The RecordStore class serves two purposes. First, it defines an API for manipulating individual records. Second, it defines an API (mostly static methods) for managing record stores.

Opening, Closing, and Removing Record Stores

To open a record store, you simply need to name it.

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

If the record store does not exist, the createIfNecessary parameter determines whether a new record store will be created or not. If the record store does not exist, and the createIfNecessary parameter is false, then a RecordStoreNotFoundException will be thrown.

The following code opens a record store named "Address."

 RecordStore rs = RecordStore.openRecordStore("Address", true);

The record store will be created if it does not already exist.

An open record store can be closed by calling the closeRecordStore() method. As with anything that can be opened and closed, it's a good idea to close record stores when you're finished with them. Memory and processing power are in short supply on a small device, so you should remember to clean up after yourself as much as possible. You probably shouldn't even keep a record store open over the lifetime of the MIDlet; after all, your MIDlet may be paused by the device's application manager, and it would be unwise to have open resources while the MIDlet is Paused.

To find out all the record stores available to a particular MIDlet suite, call the listRecordStores() method:

 public static String[] listRecordStores()

Finally, to remove a record store, call the static deleteRecordStore() method. The record store and its contained records will be deleted.

Record Store Size

Record stores consist of records; each record is simply an array of bytes. On space-constrained devices, you'll probably want to keep a close eye on the size of your record stores. To find out the number of bytes used by a record store, call the following method on a RecordStore instance:

 public int getSize()

You can find out how much more space is available by calling the following method:

 public int getSizeAvailable()

Note that this method returns the total space available in the record store, which is not the same as the amount of record data that is available. That is, there is some overhead associated with each record in the record store; the getSizeAvailable() method returns the amount of space available for both record data and overhead.

Version and Timestamp

Record stores maintain both a version number and a timestamp. The version number is updated every time the record store is modified. It is represented by an integer and can be retrieved by calling getVersion().

The record store also remembers the last time it was modified. This moment in time is represented by a long, which can be retrieved with getLastModified(). The long represents the number of milliseconds since midnight on January 1, 1970. You may recall (from Chapter 4) that this is the same way that Date uses a long to represent a moment in time. If you need to examine the timestamp of a record store, you can create a Date from the long timestamp. Then you could use a Calendar to translate from a Date to calendar fields like month, day, hour, and minute.

Team-Fly