Working with Records | ColdFusion MX Professional Projects

Team-Fly

A record is simply an array of bytes. Each record in a RecordStore is has an integer identification number. Figure 7-2 shows a diagram of a RecordStore with four records.

click to expand
Figure 7-2: Inside a RecordStore

Adding Records

To add a new record, supply the byte array to the addRecord() method:

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

The added record will be numBytes long, taken from the data array starting at offset. The new record's ID is returned. Most other record operations need this ID to identify a particular record.

The following code fragment illustrates adding a new record to a record store named rs. It creates a byte array from a String, and then writes the entire byte array into a new record.

 String record = "This is a record"; byte[] data = record.getBytes(); int id = rs.addRecord(data, 0, data.length);

Retrieving Records

You can retrieve a record by supplying the record ID to the following method:

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

This method returns a freshly created byte array containing the record with the requested ID. An alternate version of this method puts the record data into an array that you supply:

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

This method returns the number of bytes that were copied into your array. If the array you supply is not large enough to hold the record, an ArrayOutOfBoundsException will be thrown. You can find out the size of a particular record ahead of time by calling getRecordSize().

Given a RecordStore rs and a record ID id, here is one way to retrieve a record's data:

 byte[] retrieved = new byte[rs.getRecordSize(id)]; rs.getRecord(id, retrieved, 0); String retrievedString = new String(retrieved);

If you're going to be pulling many records out of the record store, you probably won't want to create a new byte array each time. For efficiency, you would create one array and use it over and over again to pull records out of the record store. One way to create the buffer is to make it as large as the largest record in the record store. If that's not practical, or if you don't know how large the largest record will be, you can simply check the size of each record before you retrieve it. If you come across a record that's larger than the buffer, you could create a larger buffer.

If you're not worried about memory usage or speed, then you might as well use the other form of getRecord(), which is essentially the same as the previous code example:

 byte[] retrieved = rs.getRecord(id);

Deleting and Replacing Records

So far you've seen how to add new records and retrieve them. There are two more record operations supported by RecordStore. First, you can remove a record by passing its ID to deleteRecord(). Second, you can replace the data of an existing record by calling the following method:

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

Getting RecordStore Record Information

The RecordStore keeps an internal counter that it uses to assign record IDs. You can find out what the next record ID will be by calling getNextRecordID(). And you can find out how many records exist in the RecordStore by calling getNumRecords().

Team-Fly