Before we dive into coding, let's take a look at RecordStore's quirks and limitations. Here's what the class javadocs say:

It's worth paying attention to that last bit—the platform will make “its best effort” to keep persistent data safe and sound. For the most part, we can assume that any given device will follow through, but we'll really need to account for the possibility that the storage might get wiped, and that we'll need to rebuild it if it's not found.

Working with a RecordStore is rather like working with a database, or with a RandomAccessFile from J2SE's java.io package. You create and access a RecordStore using a unique String ID (up to 32 Unicode characters long), and you can then add, read, set, or delete individual records of data within it. There are a bevy of new exceptions to handle with a RecordStore, which we'll touch on later.

A RecordStore is associated only with the MIDlet suite that created it. Any RecordStore created by any MIDlet within a suite is available to all other MIDlets in the same suite. However, you can't access a RecordStore in another suite.

When you add a new piece of data to a RecordStore, it's added via the addRecord() method, which returns a unique recordId int primitive that can be used to access the same record later on. The recordId is guaranteed to start at 1 for the first record of a new RecordStore, and will increment by one for each record subsequently added to it.

This recordId number increments absolutely, regardless of any record deletions. In other words, if you add three records to a new RecordStore upon creating it, their recordIds will be 1, 2, and 3 in the order in which they were added. If you then delete the second record and add an entirely new one, the recordIds will be 1, 3, and 4. Bearing this in mind, we'll use this behavior to our advantage to keep track of our images consistently—if perhaps inflexibly—although we'll hint at how to handle records in a more arbitrary fashion toward the end of the chapter (using a RecordEnumeration).

Data is stored and retrieved to and from individual records only as byte arrays, and so must be packed into byte arrays for storage, then unpacked to rebuild and use as needed by the MIDlet. We'll build some methods for doing this simply with our data.

The amount of RecordStore storage space depends wholly upon the device, and is generally shared with the MIDlet storage. In other words, don't believe you've got megabytes of memory to dump data into. You might only have some tens of kilobytes, if even that. Keep only what you need, and clear out what you don't. So, when the car's images need to change, we'll completely replace the older data with the new stuff.

Likewise, there's no guarantee that data access speed will be anything remarkable. Don't worry too much: accessing an individual record will likely only take a few milliseconds, but it may very well be much slower than using normal Java variable objects on the VM's memory heap. Furthermore, for many devices (for example, Palm Pilots), writing to memory storage is often considerably slower than reading from it, usually because of well-considered memory-locking and security.

The key here for us is that the data is persistent across “multiple invocations of the MIDlet.” This is RecordStore's best use, instead of storing and retrieving data on the fly during a MIDlet's normal operation. The rule of thumb is that for any data which should be persistent, it should be moved from normal runtime variables into the RecordStore before the MIDlet shuts down. The MIDlet should then unpack the record data into those variables when it starts up again.

Finally, a RecordStore is thread-safe. It is synchronized so that only a single running thread can access a record at a time. Remember, it's still up to the developer to make sure that, if there are multiple threads in a given MIDlet that may potentially access the same record, that they do so with some intelligence. In other words, if one thread adds records to a store and a second thread only retrieves records, the second one should be smart enough not to retrieve a particular record until the first thread has actually added it.

Those are the basic ups and downs of RecordStores, so now let's see what they can do!

A RecordStore isn't built via a constructor like most other objects; rather, it's effectively requested from the client device via a static method call:

RecordStore openRecordStore(String recordName, boolean createIfNecessary)

If a RecordStore specified by the recordName argument exists on the device, it's found and returned. If it doesn't exist and the createIfNecessary Boolean argument is true, a new RecordStore is built and returned. If an exception is thrown, it might not exist, or the device might not be able to create any new RecordStores (possibly not enough spare memory). Other useful RecordStore methods available are described in the following sections.

int addRecord(byte[] data, int offset, int numBytes)

getRecord(int recordId)

getRecord(int recordId, byte[] buffer, int offset)

setRecord(int recordId, byte[] newData, int offset, int numBytes)

deleteRecord(int recordId)

long getLastModified()

int getNextRecordID()

int getNumRecords()

getSize()

getSizeAvailable()

deleteRecordStore(String recordName)

RecordEnumeration enumerateRecords(RecordFilter filter, RecordComparator comparator,
 boolean keepUpdated)

private static final String IMAGE_STORE = "CarDB";
private Image[] weaponImages;
private byte[][] weaponImageSource;
private RecordStore imageDB;

protected boolean removeImageStore()
{
    try
    {
    if (imageDB != null
    {
        imageDB.closeRecordStore();
    }
    RecordStore.deleteRecordStore(IMAGE_STORE);
    }
    catch (RecordStoreException rse)
    {
        // The RecordStore didn't exist to delete
        // in the first place. Shouldn't be a
        // problem.
        return true
    }
    catch (Exception e)
    {
        // Something happened we can't handle
        return false;
    }
    // Removed successfully
    return true;
}

public byte[][] getImageDataFromStore()
{
    imageDB = null;
    try {
        imageDB = RecordStore.openRecordStore(IMAGE_STORE, false);

        // Get the number of records present
        int numRecords = imageDB.getNumRecords();
        // Make sure the RecordStore actually *has* some records
        if (numRecords == 0)
        {
            // The RecordStore seems to be whacked, so delete it
            // and abort
            removeImageStore();
            return null;
        }

        byte[][] allRecordData = new byte[numRecords][];
        byte[] data = null;

        // Note that we're counting the records from 1,
        // not from 0.
        for (int i = 1; i <= numRecords; i++)
        {
            data = null;
            data = imageDB.getRecord(i);
            // Note that the array index is one less than the
            // recordId.
            allRecordData[i-1] = data;
        }

        // All done, close the RecordStore
        imageDB.closeRecordStore();

        // Success!
        return allRecordData;
    }
    catch (Exception e)
    {
        // There was a problem somewhere above.
        // Make sure the RecordStore is removed.
        removeImageStore();

        // And abort
        return null;
    }
}

public void storeImageData(byte[][] imageData)
{

If (!removeImageRecord())
{
    return;
}

imageDB = null;

try {
    // This creates a new RecordStore
    imageDB = RecordStore.openRecordStore(IMAGE_STORE, true);

        int totalSize = 0;
        for (int i = 0; i < imageData.length; i++)
        {
            totalSize += imageData[i].length;
        }

        if (totalSize > imageDB.getSizeAvailable())
        {
            // bad news, just abort and return
            removeRecordStore();
            return;
        }
        // If we made it to here, it looks good and we'll likely succeed.
        for (int i = 0; i < imageData.length; i++)
        {
            imageDB.addRecord(imageData[i], 0, imageData[i].length);
        }

        imageDB.closeRecordStore();
    }
    catch (Exception e)
    {
        // Clean up and abort
       removeImageStore();
    }
}

weaponImageSource = getImageDataFromStore();
if (weaponImageSource == null)
{
    // We couldn't build the data from
    // the RecordStore so we need to
    // get them via the Internet.

    weaponImageSource = getImageDataFromServer();

    if (weaponImageSource == null)
    {
        // Now we're in trouble, we couldn't
        // build the images any which way
        // so we'll need to inform the user
        // and possibly abort the game...
    }
}

// We got the data, now build the images

weaponImages = new Image[weaponImageSource.length];
for (int i = 0; i < weaponImageSource.length; i++)
{
    weaponImages[i] = Image.createImage(weaponImageSource[i], 0, weaponImageSource[i].length);
}

storeImageData(weaponImageSource);

Storing a byte array used to create an Image is about as simple as it gets for images, but with the right combination of classes, we can actually use records and their byte array data more simply and with greater flexibility for other types of objects. We'll also get into RecordEnumerator handling here. Consider the following class in Listing 19.1.

public class CarStore
{
    // These two static final ints will
    // be used to filter the records via
    // a RecordFilter implementation.
    public static final int CASH_RECORD = 1;
    public static final int WEAPON_RECORD = 2;

    // The player's current weapons
    private Weapon[] weapons;

    // The player's current cash
    private int cash;

    // Build a new CarStore and set the
    // members
    CarStore(int cash, Weapon[] weapons) {
        this.cash = cash;
        this.weapons = weapons;
    }

    // get the current cash
    public int getCash()
    {
        return cash;
    }

    // get the current weapons array
    public Weapon[] getWeapons()
    {
        return weapons;
    }

    // Writes the cash and weapon data to a new
    // RecordStore.
    public void writeToStore()
    {
        try
        {
            // Let's make sure we're dealing with a fresh new RecordStore
            // (because we're still relying a little on recordId ordering)
            // and remove it if it's still in device storage.
            RecordStore.deleteRecordStore("MyCoolCar");

        }
        catch (Exception e)
        {
            // Shouldn't be a showstopper, so continue
        }

        // Now we can build the RecordStore from scratch
        try
        {
            // Let's make sure we're dealing with a fresh new RecordStore
            // (since we're still relying a little on recordId ordering)
            // and remove it if it's still in device storage.
            RecordStore.deleteRecordStore("MyCoolCar");
            // Now we'll create a new one.
            RecordStore carDB = RecordStore.openRecordStore("MyCoolCar", true);

            // Build some reusable data handling objects.
            ByteArrayOutputStream bout = new ByteArrayOutputStream();
            DataOutputStream dout = new DataOutputStream(bout);
            byte[] data = null;

            // Build some simple weapon description Strings
            // just to show the breadth of functionality we
            // have here.  This array is keyed to Weapon.FLAME
            // and Weapon.OIL, which are 0 and 1, respectively.

            String[] weaponName = {  "Flamer", "Oil" } ;

            // First, we're going to write the player's
            // current cash to the car's RecordStore
            // We'll id the record as a cash record...
            dout.writeByte(CASH_RECORD);

            // and then write the cash amount
            dout.writeInt(cash);

            // and now bundle the Stream into a byte
            // array and write a new record.  It's
            // the very first record in the RecordStore,
            // so we know it'll have the recordId of 1.
            data = bout.toByteArray();

            // Add the array to the RecordStore
            carDB.addRecord(data, 0, data.length );

            // and reset the Streams to
            // properly handle the Weapons.
            bout.reset();

            // Iterate through the car's Weapons array
            for (int i = 0; i < weapons.length; i++)
            {
                // Write the weapon record tag..
                dout.writeByte(WEAPON_RECORD);

                // Write the weapon name to the stream
                dout.writeUTF(weaponName[weapons[i].getWeaponType()]);

                // Write the weapon type...
                dout.writeInt(weapons[i].getWeaponType());

                // Write the weapon's ammo
                dout.writeInt(weapons[i].getWeaponAmmo());

                // and finally, the Weapon's time value
                dout.writeInt(weapons[i].getWeaponTime());

                dout.flush();

                // Pack the Byte Stream (aka the Data Stream)
                // into the data byte array...
                data = bout.toByteArray();

                // Add the array to the RecordStore
                carDB.addRecord(data, 0, data.length );

                // and reset the Streams to
                // properly handle the next Weapon.
                bout.reset();
            }	
            carDB.closeRecordStore();
            dout.close();
            bout.close();

        }
        catch (Exception e)
        {
            // handle exceptions here...
        }
}

Okay, that puts the cash and the weapons data into a RecordStore. To get it out, we're going to do things differently and use a RecordEnumerator with a custom implementation of the RecordFilter interface. If you noticed, the CASH_RECORD and WEAPON_RECORD values were written as bytes to their respective records before any of the other data. We'll use that byte to filter the records. Setting aside the CarStore class for a moment, here's our CarItemFilter class, shown in Listing 19.2.

class CarItemFilter implements RecordFilter
{
    // This will contain the car item id
    // we'll be looking for in the records.
    private byte filterValue;

    // Builds a new CarItemFilter for the
    // specific car record id we want to
    // find
    public CarItemFilter(int filterInt)
    {
        filterValue = (byte)filterInt;
    }

    // This is the RecordFilter method used
    // by the RecordEnumeration to determine
    // if the record is a "match" and needs
    // to be included in its enumeration.
    public boolean matches(byte[] candidate)
    {
        if (candidate == null || candidate.length == 0)
        {
            return false;
        }

        // Since, in the CarStore.writeToStore() method,
        // we wrote the item type byte to the records
        // before anything else, the byte at index 0
        // should be our id to filter.
        return (candidate[0] == filterValue);
    }
}

Alright! Now we're ready to get our data back out of the RecordStore. Here's the CarStore method that will do it for us:

public void readStore()
{
    try
    {
        // Open the RecordStore built above...
        RecordStore carDB = RecordStore.openRecordStore ("MyCoolCar", false);

        // Build some reusable data handling objects.
        ByteArrayInputStream bin = null;
        DataInputStream din = null;
        byte[] data = null;

        // First, we'll get the cash record out and set
        // the cash value.  Remember that this record
        // was added before any other so we know it's
        // at recordId == 1.
        data = carDB.getRecord(1);

        // Set up the streams to read back the
        // stored variables
        bin = new ByteArrayInputStream(data);
        din = new DataInputStream(bin);

        // discard the CASH_RECORD byte
        din.readByte();

        // and now grab the actual cash value stored.
        cash = din.readInt();

        // clean up for the weapons handling
        din.close();
        bin.close();

        // Prepare the Weapons array for the new data
        // (We build it to (getNumRecords()-1) to account
        // for the cash record.)
        weapons = new Weapon[carDB.getNumRecords()-1];

        // The following sets up a RecordEnumeration
        // object with our CarItemFilter RecordFilter
        // and a null RecordComparator which means
        // it will simply iterate the weapon records
        // in no particular order.  We're assuming, here,
        // that the Weapon records found won't need to be
        // in a certain sequence but can be rebuilt
        // willy-nilly.  You can always build your
        // own RecordComparator to put the enumeration into
        // some specific order.
        CarItemFilter filter = new CarItemFilter(WEAPON_RECORD);
        RecordEnumeration re = carDB.enumerateRecords(filter, null, false);

        // Prepare the necessary temp variables and
        int count = 0;
        String weaponName = "";
        int type = 0;
        int time = 0;
        int ammo = 0;
        while (re.hasNextElement())
        {
            // This next call returns the record's byte array and
            // advances the RecordEnumerator's pointer to the record
            // beyond the one returned.
            data = re.nextRecord ();

            // Set up the streams...
            bin = new ByteArrayInputStream(data);
            din = new DataInputStream(bin);

            // Read and discard the weapon record id
            din.readByte();

            // Read back the weapon name String
            weaponName = din.readUTF();
            System.out.println("Got the Weapon name: "+weaponName);

            // Read the weapon type...
            type = din.readInt();

            // Read the weapon's ammo
            ammo = din.readInt();

            // and finally, the Weapon's time value
            time = din.readInt();

            // Now rebuild the weapon into the
            // weapons array.
            weapons[count++] = new Weapon(type, time, ammo);
            // Clean up
            din.close();
            bin.close();
        }
    }
    catch (Exception e)
    {
        // handle exceptions here...
    }
  }
}

The RecordEnumeration's behavior can be further refined by building an implementation of RecordComparator. For example, we could easily implement one and make a RecordEnumerator to return weapon records ordered according to the ammo value.

There's one last interesting bit we haven't touched on yet with RecordStores. You can add a RecordListener to a RecordStore via its addRecordListener() method. The class implementing RecordListener will then be notified any time any record is added, changed, or deleted from the RecordStore.

In this chapter we looked at when (and when not) to use J2ME's RecordStore class, along with its limitations and practical work-arounds. Now you know how to directly store and retrieve data from a RecordStore, get a helping hand from the java.io package, and use RecordFilters and RecordEnumerations to store and retrieve data flexibly and consistently.