scmad chapter08

By Marcel Caraciolo

http://mobideia.blogspot.com

Chapter 08– Record Management System (RMS)

SCMAD Certification 45mm

61m

m

Agenda•MIDP - RMS•Record Management System•Record Store•Record Listener•RecordEnumeration•RecordComparator•RecordFilter•Exceptions

Record Management System

•Data may be saved to non-volatile memory on the device. This data is no lost when the application is finished or when the device is restarted. Device shall perform a best-effort service to maintain data durability.•RMS is a record-oriented system (byte arrays). A record store keeps a collection of records.•An id is created and linked to every record added to the database (record “ids” starts at 1).


•Record Stores may be shared between MIDlets and MIDlet suites, and they belong to one midlet suite. Every record store has a name (1 to 32 characters string). The Record Store belongs to the MIDlet Suite. Two records stores may have the same name as long as they belong to different suites. A suite may only remove its own record stores.•Record Stores must be opened before being used. Several calls to “open” may be done, and all point to the same record store. When a record store is not going to be used anymore, it shall be closed. To effectively close a record store we need to perform “close” the same number of opens we did.•If a Record Store belongs to the suite, we jus need its name to open it. If it belongs to other suite, we need its name, the suite name and the suite’s vendor name.


•Data Serialization shall be performed by the application. To convert data to byte arrays and vice-versa, the following classes may be used:•DataArrayOutputStream•ByteArrayInputStream•DataOutputStream•DataInputStream

•Data may be extracted from the database with RecordEnumeration, RecordComparator and RecordFilter. These classes have features similar to database SELECT statement. RecordEnumerations stands for a cursor, RecordComparator is useful for sorting and RecordFilter is useful for filtering.


•A listener may be added to a Record Store so that database events (add, deletes, updates) are informed.

•There’s no API to lock records. Accesses are serialized (and hence atomic and isolated). Concurrent operations will not corrupt the database: When two threads call setRecord over the same record at the same time, the second record overwrites the first.

•When a suite is uninstalled, all its records are removed.

•Classes at javax.microedition.rms package.

Record Store

•Both “Record Store” and “factory”

•Static methods:•openRecordStore(recordStoreName, createIfNecessary): Opens the record store. If it does not exist and createIfNecessary is true, then a record store is created. If it does not exist and createIfNecessary is false, an exception is thrown.

•deteleRecordStore(recordStoreName): Deletes a record store. It shall be closed before being removed.

Record Store

•Static methods (Continuation):

•openRecordStore(recordStoreName,createIfNecessary,authMode,writable): Opens a shared record store. Authmode is either AUTHMODE_PRIVATE or AUTHMODE_ANY, which allows sharing. If “writable” is true the other suites may write to this record store.

•openRecordStore(recordStoreName, vendorName, suiteName): Opens a record store created by other midlet suite.

•listRecordStores(): Returns a string array with the names of all record stores that belong to this suite.

Record Store: Instance methods

•getName(): Record Store Name•closeRecordStore(): Closes a record store. This must be called the same number of times that open was called to effectively close . When the record store is closed, all its listeners are removed and all its enumerations are invalidated.•setMode(authMode,writable): Changes the sharing permissions•addRecord(data[],offset,numBytes): Adds a new record to the database. The created index is returned. This operations is synchronized, blocking, atomic and durable.•getRecordSize(recordId): Size (in bytes) of a record•getRecord(recordId): Returns a byte array with the record contents.


•getRecord(recordId,buffer[],offset): Reads the record and saves its content on the array passed as parameter (this may be more memory-efficient than calling getRecord(recordId), because it will not create a new byte array for every call).

•enumerateRecords(filter,comparator,keepUpdated): Gets a set of records that are approved by the filter, sorted by comparator. If filter is null, all records are returned. If comparator is null, no sorting is defined. If keepUpdated is true, changes to the database are propagated to the enumeration. There is a performance impact when this option is used.

•setRecord(recordId, newData[], offset, numBytes): Overwrites the informed record with the new data.


•deleteRecord(recordId): Removes a record. This id will not be reused. (you can’t call setRecord with this ID again).

•getNumRecords(): Returns the number of records on the database

•getSize(): Returns how many bytes are used by the database. Includes not only the space consumed by the records, but also the overhead of handling the records.

•getSizeAvailable(): Size (in bytes) available to persistence. This values does note represent exactly the amount available to new records, since we must also consider the overhead of handling records.


•getNextRecordID(): Returns the ID that will be used for the next addRecord

•getVersion(): When the database is changed (by addRecord, deleteRecord or setRecord) this value is incremented. This can be used to check if the database was modified.

•getLastModified(): Time when the last modification happened to the database, on System.currentTimeInMilis() format.

•addRecordListener(listener): Registers a record listener

•removeRecordListener(listener): Removes a record listener

RecordListener

•Defines an object that will receive database change notifications•Methods:•recordAdded(recordStore, recordID): A record with the informed id was added to the record store•recordChanged(recordStore,recordID): A record with the informed id was modified on the record store. This is called after the modification was happened.•recordDeleted(recordStore,recordID): A record with the informed id was removed from the record store. This is called after the removal has happened.

RecordEnumeration

•Iterator over a record collection from a record store. Iterates forward and backwards.

•Records may be filtered and sorted, according to how this enumeration was created.

•It may be linked to the record store so that database modifcations are reflected on this enumeration. This impacts performance.

•If right after its creation, the first method called is previousRecord or previousRecordID, the first item to be returned is the last of this list. This can be useful for iterating from the last to the first item.

RecordEnumeration: Methods

•numRecords(): Calculates how many records are available on this enumeration. This enumeration may not be implemented as an in-memory collection, so calling this method may be a costly operation since it may force loading all data from persistence.

•nextRecord(): Returns data from the next record. Call to this method to move the iterator. If it’s called at the end of the enumeration an exception is thrown.

•nextRecordId(): Returns the record id of the next record. Calls to this method move the iterator. If it’s called at the end of the enumeration, an exception is thrown.


•previousRecord(): Returns data from the previous record. Calls to this method move the iterator. If it’s called at the beginning of the enumeration, an exception is thrown.

•previousRecordId(): Returns the id from the previous record. Calls to this method move the iterator. If it’s called at the beginning of the enumeration, an exception is thrown.

•reset(): Returns the enumeration to the state it was created

•rebuild(): Rebuilds the enumeration. Similar to call enumerateRecords again.


•hasNextElement(), hasPreviousElement(): Returns true If there are more records on the direction

•keepUpdated(booleankeepUpdated): Changes the update policy

•isKeepUpdated(): Returns true if this is a database synchronized enumeration.

•detroy(): Destroys the enumeration and frees all the resources it consumed.

RecordComparator

•Defines comparators between records. Similar to java.util’s Comparator. Used when sorting records when a RecordEnumeration is created.

•Method: compare(rec1[], rec2[]): Compare both elements. Shall returns PRECEDES if rec1 precedes rec2, FOLLOWS if rec1 follows rec2, and EQUIVALENT if the records have the same priority.

RecordFilter

•Filter elements when a RecordEnumeration is created

•Method: matches(candidate[]): Shall return true if the record shall be included on the enumeration.

Exceptions

•RecordStoreException: Generic database errors. All RMS exceptions extend this one.

•RecordStoreFullException: No more space

•RecordStoreNotFoundException: Invalid database name

•RecordStoreNotOpenException: Record Store is closed

•Invalid RecordIDException: Operation performed over an invalid record id.

Example Codes

• Some examples and MIDlets samples are available for reference and studying at this link:•http://www.dsc.upe.br/~mpc/chapter8.rar

•The source codes include:•RMSMIDlet

http://www.dsc.upe.br/~mpc/chapter7.rar

Future Work

• Next Chapter:

• CLDC - GCF• Generic Connection Framework• Connector• Connection, InputConnection, OutputConnection•StreamConnection, ContentConnection•DatagramConnection•Datagram•StreamConnectionNotifier•Exceptions

References

• ALVES F. Eduardo. SCMAD Study Guide, 27/04/2008.

• JAKL Andreas, Java Platform, Micro Edition Part 01 slides, 12/2007.

• Sun Certification Mobile Application Developer Website: [http://www.sun.com/training/certification/java/scmad.xml].

scmad chapter08

Entertainment & Humor