C H A P T E R 2 - Porting the Personal Information Management and File Connection Optional Package

C H A P T E R 2

Porting the Personal Information Management and File Connection Optional Package

This chapter discusses the design and porting of the PDA Optional Packages for the J2ME Platform (JSR 75). The JSR 75 specification defines the Personal Information Management (PIM) and File Connection (FC) optional packages. The customized version included with Java Wireless Client software is based on the Java Wireless Toolkit implementation. See http://www.jcp.org/en/jsr/detail?id=75 for more information about JSR 75.

Package Design

The file midpFileConnection.c contains a native implementation of the DefaultFileHandler class. It uses PCSL (see the Sun Java Wireless Client Porting Guide) to abstract from most system-dependent features. It calls the functions defined in midpNativeMounts.h to get native mount points. Use this API to initiate the native file system monitor, request currently mounted roots, and resolve human-friendly file root names into native file path nomenclature.

The following performance optimizations are done in midpFileConnection.c:

The connect() method converts the java.lang.String path parameter to a MidpString and stores it in memory allocated by the midpMalloc function. A pointer to this string is passed to the Java platform and saved there as a long integer object. It is used for all subsequent file operations with FileConnection objects. The memory allocated for this string is freed by the FileConnection.finalize code.

During start up, DefaultFileHandler.initialize() is called. The native implementation (in jsr75/src/kvem/native/share/midpFileConnection.c) obtains jfieldID values for all DefaultFileHandler fields accessed from native code. It determines whether they were retrieved, if they were, it saves them into native static variables.

The list of supported devices is defined by the validDisks array in midpMountedRoots.cpp. For this release, the CFCard, SDCard, and MMCCard devices are supported for the Texas Instruments OMAP730 development board, and the Floppy device is supported for the PC. The following special file roots are available for all targets: PIMdb, Storage, and Private. These roots are stored in dedicated subdirectories of the appdb directory. These directories are automatically created by the build system. The first one is used to store the PIM database, the second one can be useful if no removable devices (such as flash cards) are connected, and the third is a container for MIDlet private working directories.

The jsr75_suite_remove_cleanup() function is called when MIDlet suites are removed. It deletes the suites's private working directory and all its content.

The ROMizer is used to improve performance and security.

Porting Notes

The following table lists java.lang.System properties that must be supported by the FileConnection implementation.

TABLE 2-1 Properties That Must be Supported by a JSR 75 implementation
Property	Description
`microedition.io.file.FileConnection.version`	Specifies the version of the FileConnection API. Example: 1.0.
`microedition.pim.version`	Specifies the version of the PIM API. Example: 1.0.
`file.separator`	Returns a string that represents the file separator characters for the underlying platform. Because `pcsl_file_getpathseparator` gets the value of `file.separator`, if PCSL is ported to the target system, the system properties work correctly with no additional work.

The native file system monitor class and the file roots proxy class must be implemented for the target platform to port the JSR 75 File Connection optional package to it. These classes are required to get the mount list and to be notified of mount and unmount events. The default implementation uses polling to detect the addition and removal of file systems. If the target platform provides a mechanism that notifies you about the addition and removal of disks, it is better to customize the existing MidpFileSystemMonitor and MidpMountedRoots classes to use this mechanism.

The getMountedRoots function must return the list of mounted roots as a string where \n is a separator. According to the JSR 75 specification based on the Uniform Resource Locators specification (RFC 1738), the file root must not start with the (/) character, but must finish with the (/) character. The (/) character is the cross-platform separator used in a URL to separate directories in a path.

The current implementation posts the FC_DISKS_CHANGED_EVENT event in the Java Wireless Client software event queue after the mount list is changed. This event contains no information about which file root was mounted or unmounted. If an operating system provides details about which file root is mounted or unmounted, this information can be passed to Java Wireless Client software through the FC_DISKS_CHANGED_EVENT parameters.

Building JSR 75

To build the JSR 75 module, the following variables must be defined:

Set JSR_75_DIR to point to the JSR 75 workspace source directory.

Set USE_JSR_75 to true in the Java Wireless Client software build system.

The makefiles contain default settings that assume that USE_JSR_75 is set to false. The typical mechanism to override the default settings is to use command line settings when invoking the make command as shown in the following file fragment.

make \

USE_JSR_75=true \

JSR_75_DIR=local-path-to-JSR75 workspace \

...

Testing JSR 75

Use the following steps to configure Java Device Test Suite software version 1.4 to test the JSR 75 module:

1. Run the run_admin configuration script.

2. Open an existing profile or create a new profile that includes PDA OP (JSR 75) TestSuite (File->Open Profile or File->New Profile).

3. Select Configure Test Suites->PDA OP (JSR 75) TestSuite.

4. On the FileConnection tab specify the root directory name (for example, Storage/).

5. Select Security Permissions:

a. On the read_user_data_access tab, enable the javax.microedition.io.Connector.file.read checkbox.

b. On the write_user_data_access tab, enable the javax.microedition.io.Connector.file.write checkbox.

See the Sun Java Device Test Suite Administration Guide for more information.

JavaCall Porting Layer

FileConnection JavaCall API functions play the same role as PCSL functions do for non-JavaCall API platforms.

Personal Information Management JavaCall API functions are much like jsr75_pim_xxx() native porting layer functions.

FileConnection

FileConnection JavaCall API functions are defined in javacall_fileconnection.h header file.

All API functions listed below are mandatory. In addition to these, JSR 75 FC requires some of core MIDP JavaCall API functions (defined in javacall_file.h and javacall_dir.h) to be implemented.

The porting layer includes:

Base functions

javacall_fileconnection_init()

javacall_fileconnection_finalize()

javacall_fileconnection_get_illegal_file_name_chars()

File access functions

javacall_fileconnection_is_hidden()

javacall_fileconnection_set_hidden()

javacall_fileconnection_is_readable()

javacall_fileconnection_set_readable()

javacall_fileconnection_is_writable()

javacall_fileconnection_set_writable()

javacall_fileconnection_get_last_modified()

Directory functions

javacall_fileconnection_create_dir()

javacall_fileconnection_delete_dir()

javacall_fileconnection_rename_dir()

javacall_fileconnection_dir_exists()

javacall_fileconnection_is_directory()

javacall_fileconnection_dir_content_size()

javacall_fileconnection_get_free_size()

javacall_fileconnection_get_total_size()

Information on file system roots and special storage locations

javacall_fileconnection_get_mounted_roots()

javacall_fileconnection_get_path_for_root()

javacall_fileconnection_get_localized_mounted_roots()

javacall_fileconnection_get_photos_dir()

javacall_fileconnection_get_videos_dir()

javacall_fileconnection_get_graphics_dir()

javacall_fileconnection_get_tones_dir()

javacall_fileconnection_get_music_dir()

javacall_fileconnection_get_recordings_dir()

javacall_fileconnection_get_localized_private_dir()

javacall_fileconnection_get_localized_photos_dir()

javacall_fileconnection_get_localized_videos_dir()

javacall_fileconnection_get_localized_graphics_dir()

javacall_fileconnection_get_localized_tones_dir()

javacall_fileconnection_get_localized_music_dir()

javacall_fileconnection_get_localized_recordings_dir()

javacall_fileconnection_get_localized_private_dir()

Personal Information Management

Personal Information Management JavaCall API functions are defined in javacall_pim.h.

Implementations can provide access to PIM databases that are not resident on the device but at well known locations, located on SIM cards attached to the device, or to PIM databases created and managed by the Java platform VM itself.

All API functions listed below are mandatory, unless the Java platform implementation of PIM (based on high-level File Connection interface) is used.

The porting layer includes:

Accessing PIM list and manipulating its items

javacall_pim_list_is_supported_type()

javacall_pim_get_lists()

javacall_pim_list_open()

javacall_pim_list_close()

javacall_pim_list_get_next_item()

javacall_pim_list_add_item()

javacall_pim_list_remove_item()

javacall_pim_list_modify_item()

Accessing fields and attributes

javacall_pim_list_get_fields()

javacall_pim_list_get_attributes()

Managing categories

javacall_pim_list_add_category()

javacall_pim_list_remove_category()

javacall_pim_list_rename_category()

javacall_pim_list_max_categories()

javacall_pim_list_max_categories_per_item()

javacall_pim_list_get_categories()

JavaCall API Implementation Notes

This section describes general principles of the FC and PIM JavaCall API.

Memory Allocation

Buffers for all output parameters are allocated by the caller, unless specified otherwise.

In case of strings and arrays, there is a parameter for the size of the buffer. If output data does not fit into the buffer of the given size, the JavaCall API function must return JAVACALL_FAIL value.

Special Storage Locations

All javacall_fileconnection_get_xxx_dir() functions return paths to the directories where files of certain types are located. Each directory corresponds to one system property accessible on Java level:

fileconn.dir.photos (photos and other images)

fileconn.dir.videos (video clips)

fileconn.dir.graphics (clip art graphics)

fileconn.dir.tones (ring tones)

fileconn.dir.music (music files)

fileconn.dir.recordings (voice recordings)

fileconn.dir.private (private storage for MIDlet suites)

If any of the directories are absent (not supported) on the platform, the respective JavaCall API function should return JAVACALL_FAIL value. This will mean null value of the corresponding system property in the Java platform.

Localized Storage Directory Names

For any of the special storage locations that is supported, a localized name must also be provided. In other words, if a javacall_fileconnection_get_xxx_dir() function returns JAVACALL_OK, then the corresponding javacall_fileconnection_get_localized_xxx_dir() must also return JAVACALL_OK and provide a meaningful localized string describing the storage directory. These functions provide values for the following system properties:

fileconn.dir.photos.name

fileconn.dir.videos.name

fileconn.dir.graphics.name

fileconn.dir.tones.name

fileconn.dir.music.name

fileconn.dir.recordings.name

fileconn.dir.private.name

Platform-specific Constants

JSR 75 FC uses several platform-dependent constants that should be properly defined when implementing JavaCall API. These constants are used by the JSR code for buffers pre-allocation when calling JavaCall API functions, so their values must be sufficient as buffer sizes to hold file names, root lists, and other native file system data:

JAVACALL_MAX_FILE_NAME_LENGTH - maximum length of a file name allowed the file system, located in the javacall_file.h

JAVACALL_MAX_ILLEGAL_FILE_NAME_CHARS - maximum number of characters that cannot be used in file names, located in the javacall_file.h

JAVACALL_MAX_ROOTS_LIST_LENGTH - maximum length of a string with a list of all roots provided by the device, located in the javacall_dir.h

JAVACALL_MAX_ROOT_PATH_LENGTH - maximum length of native (file system-specific) path to any of the roots, located in the javacall_dir.h

JAVACALL_MAX_LOCALIZED_ROOTS_LIST_LENGTH - maximum length of a string with a list of localized names of all file system roots, located in the javacall_fileconnection.h

JAVACALL_MAX_LOCALIZED_DIR_NAME_LENGTH - maximum length of localized name of a special directory (e.g. private, music, photos...), located in the javacall_fileconnection.h

Callback functions

javanotify_fileconnection_root_changed()

This function must be called by the platform every time a file system root gets mounted or unmounted. The function body is platform-independent (implemented by Sun) and does not require any porting.

JavaCall API implementation must notify Java of mount/unmount events as soon as possible - ideally, platform may have an efficient mechanism to invoke the callback function immediately upon root change.

JavaCall API Porting Steps

This section explains how the JSR 75 code can be ported to a new platform using the JavaCall API. The new platform is represented here as <new_platform>.

File Connection Implementation

1. Create <new_platform>/jsr75_pim_fc directory in the javacall-com/implementation directory.

2. Copy fileconnection.c from javacall-com/implementation/stubs/jsr75_pim_fc to the <new_platform>/jsr75_pim_fc directory.

3. Rewrite functions in your new fileconnection.c according to the platform specifics.

4. Adjust platform-specific file system constants in javacall_file.h, javacall_dir.h, and javacall_fileconnection.h as necessary.

PIM Implementation

1. Create <new_platform>/jsr75_pim_fc directory in the javacall-com/implementation directory.

2. Copy pim.c from javacall-com/implementation/stubs/jsr75_pim_fc to the <new_platform>/jsr75_pim_fc directory.

3. Rewrite functions in your new pim.c according to the platform specifics.

4. Set the appropriate values for PIMRootDir and file.linebreak in jsr75/src/config/javacall/properties_jsr75.xml.

5. Set value for JSR_75_PIM_HANDLER_IMPL to platform in jsr75/src/config/common/config.gmk file.