Record Management System di J2ME

Data storage and retrieval is an essential aspect of application development. The data that is stored will depend on the type and complexity of the application. In some cases the only persistent data to be stored is the application user preferences. In other cases you may need to store and manage a repository of contact information. On the high end, you could be designing a data storage solution for a full range of supply-chain data. No matter what the case, there is just one all-purpose data storage and management solution for MIDP-enabled devices, and that is the Record Management System (RMS).

In this article, the first of a companion series to the two-part J2ME 101 tutorial series, we’ll explore the inner workings of MIDP’s persistent storage system. We’ll start with a quick overview of RMS, but most of the article (like the tutorial series) will be hands-on. Together, we’ll build MIDlets that will help you understand how data records are written to and read from the RMS, as well as the variety of sorting, searching, and retrieval options that are available within this remarkably well-rounded and compact data management system.

Please note that this article assumes that you are familiar with MIDlet development in the J2ME environment. You will need to have a J2ME development environment installed on your system in order to compile the code examples. See the Resources section for links to installation instructions for the J2ME Wireless Toolkit (WTK).

Record management in MIDP

Put simply, the MIDP Record Management System (RMS) provides a means to store application data that persists across invocations of a MIDlet. You can visualize the RMS record store as a very simple database, where each row consists of two columns: one containing a unique row identifier, the other a series of bytes representing the data in the record. Table 1 illustrates a simple record store database.
Table 1. A record store database

Record ID Data

1  Array of bytes

2   Array of bytes

3 Array of bytes

…

The unique row identifer is an integer value. The first entry will have the ID of 1, the next of 2, and so on. Row identifiers are not re-used if a row is deleted. That is, if we have three rows in a table with the IDs 1, 2, and 3, deleting ID 2 will remove this identifier permanently from the record store. If we were to add another row to this table, it would have an identifier of 4.

Record stores are identified by name. A name may consist of up to 32 characters, and all characters are case sensitive. No two record stores within a MIDlet suite (that is, a collection of one or more MIDlets packaged together) may contain the same name.

Each record store has a version number as well as a date/time stamp. Both values are updated whenever a record is added, replaced, or deleted.

No constructor exists for creating a record store. Instead, we use a set of three dual-purpose methods to create and/or open record stores. Each method is shown in Listing 1.
Listing 1. Creating and opening record stores

RecordStore openRecordStore(String recordStoreName,
                               boolean createIfNecessary)
RecordStore openRecordStore(String recordStoreName,
                               boolean createIfNecessary,
                               int authmode,
                               boolean writable)
RecordStore openRecordStore(String recordStoreName,
                               String vendorName,
                               String suiteName)

The first method opens the named record store if it exists. If the named record store does not exist, and if the parameter createIfNecessary is set to true, the method can be used to create a new (named) record store. The second method operates in the same fashion but employs two additional parameters to specify the record store’s access restrictions. The first parameter specifies whether or not only those MIDlets in the same suite can access the record store. The second one specifies whether MIDlets that have access to the record store, can create new records. The last method provdes a means for a MIDlet to open a record store in another MIDlet suite.

The RecordStore API

A handful of methods are available for working with a record store. These range from adding, deleting, and replacing record contents to enumerating through a record store. Each available method is shown in Listing 2.

void closeRecordStore()
void deleteRecordStore(String recordStoreName)
String[] listRecordStores()
int addRecord(byte[] data, int offset, int numBytes)
void setRecord(int recordId, byte[] newData, int offset, int numBytes)
void deleteRecord (int recordId)
byte[] getRecord (int recordId)
int getRecord (int recordId, byte[] buffer, int offset)
int getRecordSize (int recordId)
int getNextRecordID()
int getNumRecords()
long getLastModified()
int getVersion()
String getName()
int getSize()
int getSizeAvailable()
RecordEnumeration enumerateRecords(RecordFilter filter,
                                      RecordComparator comparator,
                                      boolean keepUpdated)
void addRecordListener (RecordListener listener)
void removeRecordListener (RecordListener listener)
void setMode(int authmode, boolean writable)

You’ll learn more about the RecordStore API and many of its methods as we work through the examples in the sections that follow.

The ReadWrite MIDlet

Our first illustrative example is the ReadWrite MIDlet. This MIDlet has the ability to create a record store, write several records into persistent storage, read back those same records, and delete the record store upon exiting. As you study the code below, note that the MIDlet contains several “convenience” methods, which are methods used time and again when working with the RMS. Convenience methods are the methods used to open, close, and delete record stores.

Take a look at the complete code for the ReadWrite MIDlet and then we’ll discuss it in more detail.

Notes about the code

A couple of points are worth mentioning before we move on. First, note that in this example we created a new record store by passing true for the createIfNecessary parameter when calling RecordStore.openRecordStore(REC_STORE, true), as previously explained.

Second, when we wrote to the record store with writeRecord(String str), we first converted the Java string parameter into a byte array. This byte array was then passed to addRecord(rec, 0, rec.length) to insert a record into the record store.

Finally, in the readRecords() method we allocated a byte array to store any record data we read from the RMS. This allows us to make a specific check on each read to ensure that the array is large enough to hold the data. Once the record has been retrieved, we can output the contents to the console.

Figure 1 shows the output of the ReadWrite MIDlet when it is run from within the J2ME WTK.
Figure 1. Record output from the ReadWrite MIDlet

Read and write Java primitives

The ReadWrite MIDlet only writes text strings to the record store. For the next example, we’ll add the ability to store and manipulate arrays of integer, boolean, and string values. We’ll also add support for reading and writing using Java streams. As with the previous example, we’ll write several records and then read them back from the store.

As with any MIDlet that needs to access the record store, we begin by using the openRecordStore() method to allocate and open (or create) a record store, as shown in Listing 3.
Listing 3. Create a record store

private RecordStore rs = null;    // Record store
...

public void openRecStore()
{
     ...
     // Create record store if it does not exist
     rs = RecordStore.openRecordStore(REC_STORE, true);
     ...
}

Listing 4 shows the primitive data types we’ll write to the record store.
Listing 4. Java primitive data types

public void writeTestData()
{
     boolean[] booleans = {true,false};
     int[] integers = {17 , 4};
     String[] strings = {"Golf", "Tennis"};

     writeStream(booleans, integers, strings);
}

If you’re familiar with using streams in the Java language, you’ll find little difference between working with a MIDlet and with a more traditional Java application. The steps are as follows:

• Allocate streams
• Write the data
• Flush the stream
• Transfer the stream data into an array
• Write the array to the record store
• Close the streams

Listing 5 shows how to write to RMS using a stream:

public void writeStream(boolean[] bData, int[] iData, String[] sData)
{
     try
     {
        // Write data into an internal byte array
       ByteArrayOutputStream strmBytes = new ByteArrayOutputStream();

       // Write Java data types into the above byte array
       DataOutputStream strmDataType = new DataOutputStream(strmBytes);

       byte[] record;

       for (int i = 0; i < sData.length; i++)
       {
         // Write Java data types
         strmDataType.writeBoolean(bData[i]);
         strmDataType.writeInt(iData[i]);
         strmDataType.writeUTF(sData[i]);

         // Clear any buffered data
         strmDataType.flush();

         // Get stream data into byte array and write record
         record = strmBytes.toByteArray();
         rs.addRecord(record, 0, record.length);

         // Toss any data in the internal array so writes
         // starts at beginning (of the internal array)
         strmBytes.reset();
       }

       strmBytes.close();
       strmDataType.close();

     }
     catch (Exception e)
     {
       db(e.toString());
     }
}

Next we want to read from the record store. We begin by creating the necessary input streams, then loop through each record, storing its contents in a byte array. Accessing the data input stream we read each Java primitive type from the byte array and print the associated contents to the console, as shown in Listing 6.
Listing 6. Reading a stream from the record store

public void readStream()
{
     try
     {
       // Allocate space to hold each record
       byte[] recData = new byte[50];

       // Read from the specified byte array
       ByteArrayInputStream strmBytes = new ByteArrayInputStream(recData);

       // Read Java data types from the above byte array
       DataInputStream strmDataType = new DataInputStream(strmBytes);

       for (int i = 1; i <= rs.getNumRecords(); i++)
       {
         // Get data into the byte array
         rs.getRecord(i, recData, 0);

         // Read back the data types
         System.out.println("Record #" + i);
         System.out.println("Boolean: " + strmDataType.readBoolean());
         System.out.println("Integer: " + strmDataType.readInt());
         System.out.println("String: " + strmDataType.readUTF());
         System.out.println("--------------------");

         // Reset so read starts at beginning of array
         strmBytes.reset();
       }

       strmBytes.close();
       strmDataType.close();

     }
     catch (Exception e)
     {
       db(e.toString());
     }
}

Now check out the source code for the ReadWritePrimitives MIDlet. Study it carefully, and then run the code in your WTK emulator to view the output if you like.

The console output for the ReadWritePrimitives MIDlet should look as shown in Figure 2.
Figure 2. Output of the ReadWritePrimitives MIDlet

Building a comparator

For the most part, the code for the IntegerSort MIDlet (see the complete source code) won’t differ much from that of our previous MIDlets. The biggest change is the addition of a comparator class (Listing 13) and the methods for extracting the appropriate fields and performing the actual sorting. Following is the ComparatorInteger class that handles all the details for the IntegerSort MIDlet.
Listing 13. The ComparatorInteger class

/*--------------------------------------------------
* Compares two integers to determine sort order
* Each record passed in contains multiple Java data
* types - use only the integer data for sorting
*-------------------------------------------------*/
class ComparatorInteger implements RecordComparator
{
     private byte[] recData = new byte[10];

     // Read from a specified byte array
     private ByteArrayInputStream strmBytes = null;

     // Read Java data types from the above byte array
     private DataInputStream strmDataType = null;

     public void compareIntClose()
     {
       try
       {
         if (strmBytes != null)
           strmBytes.close();
         if (strmDataType != null)
           strmDataType.close();
       }
       catch (Exception e)
       {}
     }

     public int compare(byte[] rec1, byte[] rec2)
     {
       int x1, x2;

       try
       {
         // If either record is larger than our buffer, reallocate
         int maxsize = Math.max(rec1.length, rec2.length);
         if (maxsize > recData.length)
           recData = new byte[maxsize];

         // Read record #1
         // We want the integer from the record, which is
         // the second "field" thus we must read the
         // String first to get to the integer value
         strmBytes = new ByteArrayInputStream(rec1);
         strmDataType = new DataInputStream(strmBytes);
         strmDataType.readUTF();       // Read string
         x1 = strmDataType.readInt();  // Read integer

         // Read record #2
         strmBytes = new ByteArrayInputStream(rec2);
         strmDataType = new DataInputStream(strmBytes);
         strmDataType.readUTF();       // Read string
         x2 = strmDataType.readInt();  // Read integer

         // Compare record #1 and #2
         if (x1 == x2)
           return RecordComparator.EQUIVALENT;
         else if (x1 < x2)
           return RecordComparator.PRECEDES;
         else
           return RecordComparator.FOLLOWS;

       }
       catch (Exception e)
       {
         return RecordComparator.EQUIVALENT;
       }
     }

Pay close attention to the code for reading the Java primitives. We need to retrieve the integer value from each record. However, this value is the second “field” stored in each record. Therefore, we simply read the string (UTF) value and toss it aside. The second read stores the integer value in a local variable (x1 or x2). These values are then compared to determine the proper sort order.

// Read record #1
...
strmDataType.readUTF();       // Read string
x1 = strmDataType.readInt();  // Read integer

// Read record #2
...
strmDataType.readUTF();       // Read string
x2 = strmDataType.readInt();  // Read integer

// Compare record #1 and #2
if (x1 == x2)
     return RecordComparator.EQUIVALENT;
else if (x1 < x2)
     return RecordComparator.PRECEDES;
else
     return RecordComparator.FOLLOWS;

Building an enumerator

With the comparator code written, we next create an enumerator, referencing an instance of the ComparatorInteger class. The enumerator will create a result set of records from the record store, using the comparator as the sorting algorithm. Listing 15 is a partial listing of the readStream() method which creates the comparator as well as the enumerator, and loops through the result set displaying record contents on the console.
Listing 15. readStream() method

public void readStream()
{
    ...

     if (rs.getNumRecords() > 0)
     {
       // Create instance of the comparator
       ComparatorInteger comp = new ComparatorInteger();

       // Create enumerator, referencing the comparator
       RecordEnumeration re = rs.enumerateRecords(null, comp, false);

       // Loop through all elements in the result set
       int i = 1;
       while (re.hasNextElement())
       {
         // Get data into the byte array
         rs.getRecord(re.nextRecordId(), recData, 0);

         // Read back the data types
         System.out.println("Record #" + i++);

         System.out.println("String: " + strmDataType.readUTF());
         System.out.println("Integer: " + strmDataType.readInt());
         System.out.println("--------------------");

         // Reset so read starts at beginning of array
         strmBytes.reset();
       }

     ...

}

The RecordFilter API

Sorting with a comparator is one option when working with an enumerator, searching with a filter is the other. A minor difference between a comparator and a filter is that a comparator returns the entire record store in sorted order, whereas a filter returns only those records that match a specified criteria. If you apply both a comparator and a filter, records that match the search criteria will be returned in sorted order.

Like the RecordComparator, the RecordFilter is implemented by the addition of a single method, matches(), to the enumerator code. The enumerator calls thematches() method for each record in the store. Based on the boolean return value, the record either becomes a member of the result set or is tossed aside as a record that does not meet the search criteria.
Listing 16. The RecordFilter API’s matches() method

boolean matches(byte[] candidate)

Listing 17 shows a class that implements the RecordFilter interface. Notice that the search string is specified as a parameter to the constructor SearchFilter. The string is saved in a private variable so we have access to the string when the enumerator calls the matches() method to create the result set. For this example, the search string is also converted to lowercase, resulting in a search that is not case-sensitive.
Listing 17. Building a RecordFilter

//********************************************************
// Create filter class for searching
//********************************************************
class SearchFilter implements RecordFilter
{
     private String searchText = null;

     public SearchFilter(String searchText)
     {
       // Text to find
       this.searchText = searchText.toLowerCase();
     }

     public boolean matches(byte[] candidate)
     {
       String str = new String(candidate).toLowerCase();

       // Does the text exist?
       if (searchText != null && str.indexOf(searchText) != -1)
         return true;
       else
         return false;
     }
}

...

//********************************************************
// How to access the filter using a record enumeration
//
// Note: Variable 'rs' is created outside the scope of
//       this method
//********************************************************
// Create search filter
SearchFilter search = new SearchFilter("abc");

// Reference filter when creating the result set
RecordEnumeration re = rs.enumerateRecords(search, null, false);

// If there is at least one record in result set, a match was found
if (re.numRecords() > 0)
{
     // At least one record in the result set, do something here...
     ...
}

Note that the actual code that performs the search in this example is quite trivial. Using the Java string method indexOf(), we look for the specified search string and return a boolean value indicating success or failure.

We’ll build one last MIDlet to illustrate what you’ve learned so far. (Here’s the complete source for the StringSearch MIDlet.) In addition to allowing us to search the RMS for records, this MIDlet beefs up the user interface we’ve worked with so far. Instead of using only the console for output, we’ll display a TextField component (which you should recall from the tutorial series!) that will prompt the user for a text string. When requested, we’ll search the record store for the string. Any and all matches will be appended on the display, showing the search results.

Listing 18 shows the search strings that will be written into the record store.
Listing 18. Entries to the record store

public void writeTestData()
{
     String[] strs = {
                     "I think this would be a good time for a beer. (FDR)",
                     "I'll make it a felony to drink small beer. (Shakespeare)",
                     "They who drink beer will think beer. (Washington Irving)",
                     "I would give all my fame for a pot of ale. (Shakespeare)"};
     writeRecords(strs);
}

Figure 4 shows the MIDlet with two different search results.

sumber: ibm.com

No related posts.

Related posts brought to you by Yet Another Related Posts Plugin.