Chapter   4

Persistent Storage

This chapter discusses how to port and customize the persistent storage functionality. Persistent storage enables data to be kept on a device both across uses of a MIDlet suite and across shut downs and restarts of the device. The functionality is used by the Record Management System (RMS), by the application management system (AMS), by the native code that manages system configuration, by the security module, and can also be used by MIDlet suites.

The persistent storage implementation provides a flat file system, which is a file system that puts its files in a single directory. Because there are no subdirectories, each file must have a unique name.

The persistent storage implementation has both a native layer and a Java™ programming language layer (Java layer). The files in the native layer are RandomAccessStream.c, storageFile.c, storage.h, and storage.c in the src/share/native/ directory. The classes in the Java layer are RandomAccessStream and File in the com.sun.midp.io.j2me.storage package.

To port persistent storage, you must make the native layer run on your device. To customize persistent storage, you also modify the Java layer.

This chapter contains the sections:

Porting the Native Layer
Customizing the Java Layer

4.1 Porting the Native Layer

The native layer of the persistent storage implementation is in the
src/share/native/ directory, in the files storage.h, storage.c and storageFile.c:

storage.h — defines the macros and declares the functions for the persistent storage implementation. You should not need to change this file.
storage.c — defines the functions that interact with the persistent storage of the device, including opening, reading, and writing files. This file requires porting.
storageFile.c — defines the functions that mediate between the Java and native layers. The functions in this file use KNI; you should not need to change them. (For more information on KNI, see your CLDC documentation.)

The way that you port storage.c depends on the capabilities of your device. If your device has a file system interface that supports directory hierarchies, you could customize the existing code. To do this, start with the code between these lines:

#ifdef UNIX 
#endif /* UNIX */ 

It uses the following system APIs for file manipulation:

open
close
read
write
stat
lseek
ftruncate
fstat

Note that fstat is used only to get file size; if your device has another call that returns a file’s size, that call is sufficient.

unlink
rename

It also includes the following directory operations:

mkdir
opendir
readdir
closedir

If your platform has another type of interface, such as record-oriented file system or a flat-file interface, reimplement storage.c to use it. (In these cases, you might also change the Java layer.)

4.2 Customizing the Java Layer

The Java layer runs without changes on a new device. You might want to customize it if your device has an alternate storage mechanism. For example, if the device has a record-based storage system (such as a database), the RMS APIs might map directly or nearly directly to native methods. Using native methods (instead of the RI’s Java layer) would not only give MIDlets RMS performance that is similar to a native application, you could probably also remove much of the record handling code.

Note, though, that not all devices provide fast native storage operations. If your device does not, you should try to minimize the memory access operations done by your port by using caching.

Another example of an alternate storage mechanism is a device that has a full-featured file system. For this type of device, you might decide to map record stores to directories and records to files. (In the RI, a record store is a file and the records within them are blocks of data in the file.) This would allow the file system to handle most of the metadata maintained in each record store now (such as the modification time, version information, and so on) and therefore to remove much of the code in the RecordStore class.

As you customize the RMS, pay attention to any system storage limitations on your device. RMS gives record stores names that are case sensitive and can be up to 32 Unicode characters in length. If your device is case insensitive, or requires shorter names, you will have to use a different mechanism (such as a map table) to map a MIDlet suite's RMS record store name to a name on your device.

Porting MIDP MIDP Reference Implementation, Version 2.0 FCS

Copyright © 2002 Sun Microsystems, Inc. All rights reserved.