Programming Tutorials

RMS Basics in J2ME

By: Daniel Malcolm in J2ME Tutorials on 2007-09-17  

Each MIDP-compliant device maintains a dedicated area of device memory for persistent application data storage. MIDlet data stored here persists across multiple invocations of the applications that use it. Both the physical location and the size of the data store are device dependent.

The RMS API abstracts the device-dependent details of the storage area and access to those details, and it provides a uniform mechanism to create, destroy, and modify data. This ensures portability of MIDlets to different devices.

RMS Data Storage Model

The RMS supports the creation and management of multiple record stores, shown in Figure below. A record store is a database whose central abstraction is the record. Each record store consists of zero or more records. A record store name is case sensitive and can consist of a maximum of 32 Unicode characters. A record store is created by a MIDlet.

MIDlets within the same MIDlet suite can share one another's record stores. A MIDlet suite defines a name space for record stores; a record store must have a unique name within a MIDlet suite. The same name can be used in different MIDlet suites, however.

MIDlets can list the names of all the record stores available to them. They can also determine the amount of free space available for storing data. Incidentally, you should be aware that when all MIDlets in a MIDlet suite are removed from a device, the device AMS removes all record stores in the MIDlet suite namespace. All persistent data will be lost. For this reason, you should consider designing applications to include a warning or confirmation that requires users to acknowledge that they understand the potential loss of data when they remove applications. Applications might also include a mechanism to back up the records in a data store to another location. This might require server side support.

The RMS defines the following conceptual operations on an individual record store:

• Add a record.
• Delete a record.
• Change a record.
• Look up (retrieve) a record.
• Enumerate all records.

Records are uniquely identified by a record ID, which is the only primary key type supported. The type of all record ids is the Java built-in type int. The RMS has no support for features-such as tables, rows, columns, data types, and so forth-that are present in relational databases.

Records

A record is a byte array of type byte []. The RMS doesn't support the definition or formatting of fields within a record. Your application must define the data elements within a record and their format.

The reader of a record, therefore, must be aware of the format that was used to write the record. Because a record is simply a byte array, applications must convert data from arbitrary types to bytes when writing records, and they must convert from bytes to those types upon reading the data.

Here is a sample code that shows simple read and write of RMS in J2ME

import javax.microedition.midlet.*;
import javax.microedition.lcdui.*;
import javax.microedition.io.*;
import javax.microedition.rms.*;

public class ReadWriteRMS extends MIDlet{
  private RecordStore rs = null;
  static final String REC_STORE = "ReadWriteRMS";

  public void startApp(){
    openRecStore();
    writeRecord("Core J2ME Technology");
    writeRecord("J2ME Wireless Toolkit");    
    readRecords();
    closeRecStore();
    deleteRecStore(); 
  }

  public void pauseApp(){}

  public void destroyApp(boolean unconditional){
    notifyDestroyed();
  }

  public void openRecStore(){
    try{
      rs = RecordStore.openRecordStore(REC_STORE, true );
    }catch (Exception e){}
  }    

  public void closeRecStore(){
    try{
      rs.closeRecordStore();
    }catch (Exception e){}
  }

  public void deleteRecStore(){
    if (RecordStore.listRecordStores() != null){
      try{
        RecordStore.deleteRecordStore(REC_STORE);
      }catch (Exception e){}
    }      
  }

  public void writeRecord(String str){
    byte[] rec = str.getBytes();
    try{
      rs.addRecord(rec, 0, rec.length);
    }catch (Exception e){}
  }

  public void readRecords(){
    try{
      byte[] recData = new byte[5]; 
      int len;
      
      for(int i = 1; i <= rs.getNumRecords(); i++){
        if(rs.getRecordSize(i) > recData.length){
          recData = new byte[rs.getRecordSize(i)];
        }
        len = rs.getRecord(i, recData, 0);
        System.out.println("------------------------------");
        System.out.println("Record " + i + " : " + new String(recData, 0, len));
        System.out.println("------------------------------");                        
      }
    }catch (Exception e){}
  }
}