Persistent Storage in MIDP

1
Persistent Storage in MIDP

• Yin-Hsong Hsu
• Nov. 2002

2
Introduction

• The MIDP provides a mechanism for MIDlets to
  persistently store data and retrieve it later
• This persistent storage mechanism, called the
  Record Management System (RMS), is modeled after
  a simple record-oriented database

3
Record Store

• A record store consists of a collection of
  records that will remain persistent across
  multiple invocations of a MIDlet
• Record stores are created in platform-dependent
  locations, which are not exposed to MIDlets
• The naming space for record stores is controlled
  at the MIDlet suite granularity
• MIDlets within a MIDlet suite are allowed to
  create multiple record stores

4

• Only allow the manipulation of the MIDlet suites
  own record stores
• Do not provide any mechanism for record sharing
  between MIDlets in different MIDlet suites
• MIDlets within a MIDlet suite can access one
  anothers record stores directly.

5

• Record store names are case sensitive and may
  consist of any combination of up to 32 Unicode
  characters
• No locking operations are provided
• Record store implementations ensure that all
  individual record store operations are atomic,
  synchronous, and serialized so that no corruption
  occurs with multiple accesses

6

• The record store is time stamped with the last
  time it was modified
• The record store also maintains a version
• These are useful for synchronization engines as
  well as applications

7
Records

• Records are arrays of bytes
• Developers can use DataInputStream and
  DataOutputStream as well as ByteArrayInputStream
  and ByteArrayOutputStream to pack and unpack
  different data types into and out of the byte
  arrays

8

• Records are uniquely identified within a given
  record store by their recordId, which is an
  integer value
• recordId is used as the primary key for the
  records
• The first record created in a record store will
  have recordId equal to 1, and each subsequent
  recordId will monotonically increase by one
• MIDlets can create other indices by using the
  RecordEnumeration class

9
(No Transcript)
10
Classes for Record Store

• Package javax.microedition.rms
• Classes
• RecordStore, RecordEnumeration
• Interfaces
• RecordComparator, RecordFilter, RecordListener
• Exceptions
• RecordStoreException, RecordStoreFullException,
  RecordStoreNotFoundException, InvalidRecordExcepti
  on, RecordStoreNotOpenException

11
Management of Record Store

• openRecordStore()
• closeRecordStore()
• listRecordStore()
• deleteRecordStore()
• getVersion(), getLastModified()

12

• openRecordStore
• static RecordStore openRecordStore
  (recordStoreName,  createIfNecessary)
• Open (and possibly create) a record store
  associated with the given MIDlet suite
• Exceptions
• RecordStoreException, RecordStoreFullException,
  RecordStoreNotFoundException

13

• closeRecordStore
• Exception
• RecordStoreException, RecordStoreNotOpenException
• listRecordStores
• static String listRecordStores()
• Returns an array of the names of record stores
  owned by the MIDlet suite

14

• deleteRecordStore
• static deleteRecordStore (recordStoreName)
• Exceptions
• RecordStoreException, RecordStoreNotFoundException
  
• Version
• int getVersion()
• Last modified date
• long getLastModified()

15
An example

• RecordStoreTest.java

open
close
16
Records

• Records are arrays of bytes
• Developers can use DataInputStream and
  DataOutputStream as well as ByteArrayInputStream
  and ByteArrayOutputStream to pack and unpack
  different data types into and out of the byte
  arrays

17

• Records are uniquely identified within a given
  record store by their recordId, which is an
  integer value
• recordId is used as the primary key for the
  records
• The first record created in a record store will
  have recordId equal to 1, and each subsequent
  recordId will monotonically increase by one
• MIDlets can create other indices by using the
  RecordEnumeration class

18
(No Transcript)
19
Record Manipulation

• Basic manipulation
• addRecord(), deleteRecord(), and getRecord(),
  setRecord()
• Information retrieval
• getNumRecords() , getRecordSize()
• Information about a record
• getSize(), getSizeAvailable()
• Enumeration
• getNextRecordID()

20
Basic Record Manipulation

• addRecord
• int addRecord(byte data, int offset,
  int numBytes)
• Adds a new record to the record store
• The recordId for this new record is returned
• deleteRecord
• void deleteRecord(int recordId)
• The record is deleted from the record store

21

• getRecord
• int getRecord(int recordId, byte buffer,
  int offset)
• Returns the data stored in the given record
• Return ? the number of bytes copied into the
  buffer
• byte getRecord(int recordId)

22

• setRecord
• void setRecord(int recordId, byte newData,
  int offset, int nBytes)
• Sets the data in the given record to that passed
  in
• An example CharRecordStoreTest.java

23
byte tmp new byte2 tmp0 (byte)(0xff(
data gtgt 8)) tmp1 (byte)(0xff( data gtgt
0)) try return rs.addRecord(tmp,0,tmp.length)
catch(Exception e)
byte tmp new byte2 try tmp
rs.getRecord(recordid) catch(Exception e)
char result (char)tmp0 result
(char)((result ltlt 8) (char)tmp1) return
result
24

• Another example DataRecordStoreTest.java
• Making use of stream classes for handling bytes
  and chars
• ByteArrayOutputStream, ByteArrayInputStream,
  DataOutputStream, DataIntputStream

ByteArrayOutputStream
DataOutputStream
25
public byte encode() byte result null
try ByteArrayOutputStream bos new
ByteArrayOutputStream() DataOutputStream dos
new DataOutputStream (bos) dos.writeUTF(name)
dos.writeUTF(tel) dos.writeBoolean(sex)
dos.writeInt(age) result
bos.toByteArray() dos.close() bos.close()
catch(Exception e) return result

ByteArrayOutputStream
DataOutputStream
26
public void decode(byte data) try
ByteArrayInputStream bis new
ByteArrayInputStream(data) DataInputStream dis
new DataInputStream (bis) name
dis.readUTF() tel dis.readUTF() sex
dis.readBoolean() age dis.readInt()
dis.close() bis.close()
catch(Exception e)
ByteArrayIntputStream
DataInputStream
27
Monitoring Record Changing

• RecordListener
• recordAdded(recordStore, recordID)
• recordChanged(recordStore, recordID)
• recordDeleted(recordStore, recordID)
• RecordStore
• addRecordListener(listener)
• removeRecordListener(listener)
• An example RLTest.java

28
Information retrieval

• getNumRecords
• int getNumRecords()
• Returns the number of records currently in the
  record store
• getRecordSize
• int getRecordSize(int recordId)
• Returns the size (in bytes) of the MIDlet data
  available in the given record

29
Information about a record

• getSize
• int getSize()
• Returns the amount of space, in bytes, that the
  record store occupies
• getSizeAvailable
• int getSizeAvailable()
• Returns the amount of additional room (in bytes)
  available for this record store to grow

30
Enumeration

• getNextRecordID
• int getNextRecordID()
• Returns the recordId of the next record to be
  added to the record store

31
RecordEnumeration

• An interface logically maintains a sequence of
  the recordId's of the records in a record store
• Methods
• hasNextElement(), hasPreviousElement()
• nextRecord(), nextRecordId()
• previousRecord(), previousRecordId()
• numRecords()

32

• An example RETest.java

try RecordEnumeration re
rs.enumerateRecords(null,null,false)
System.out.println("There are "
re.numRecords() " in RecordStore")
while(re.hasNextElement()) byte tmp
re.nextRecord() System.out.println(tmp0 "
" tmp1) catch (Exception e)
33
RecordComparator

• An interface defining a comparator which compares
  two records (in an implementation-defined manner)
  to see if they match or what their relative sort
  order is
• Define a method for comparison
• int compare(byte rec1, byte rec2)
• Returns
• PROCEEDS, FOLLOWS, EQUIVALENT

34
RecordComparator c new AddressRecordComparator()
// class implements RecordComparator if
(c.compare(recordStore.getRecord(rec1),
recordStore.getRecord(rec2))
RecordComparator.PRECEDES) return rec1
35

• An example MyAddressBook.java