16 JSR 75: PDA Optional Packages

16.1 FileConnection API

On a real device, the FileConnection API typically provides access to files stored in the device's memory or on a memory card.

In the Java ME SDK emulator, the FileConnection API enables MIDlets to access files stored on your computer's hard disk.

The files that can be accessed using the FileConnection optional package are stored in the following subdirectory:

Documents and Settings\user\javame-sdk\3.0.5\work\emulator-instance\appdb\filesystem

For example, the DefaultCldcPhone1 emulator instance comes with a root directory installed called root1, which contains a Readme file and an empty directory named photos.

Each subdirectory of filesystem is called a root. The Java ME SDK provides a mechanism for managing roots. While the emulator is running, choose Device > File Connection. The opens with the File Connection tab selected.

In the File Connection panel you can mount, unmount, or delete filesystem roots. Mounted roots are displayed in the top list, and unmounted roots are moved to the bottom list. Mounted root directories and their subdirectories are available to applications using the FileConnection API. Unmounted roots can be remounted in the future.

• To add a new empty filesystem root directory, click Mount Empty and fill in a name for the directory.

• To mount a copy of an existing directory, click Mount Copy, and browse to choose a directory you want to copy. When the File System Root Entry dialog opens, enter the name for this root. A deep copy of the selected directory is placed into the emulator's filesystem with the specified root name.

• To make a directory inaccessible to the FileConnection API, select it in the list and click Unmount. The selected root is unmounted and moved to the Unmounted roots list.

• To completely remove a mounted directory, select it and click Unmount & Delete.

• To remount an unmounted directory, select it and click Remount. The root is moved to the mounted roots list.

• To delete an unmounted directory, select it and click Delete. The selected root is removed from the list.

16.2 PIM API

The Java ME SDK emulator stores contact, calendar, and to-do information in standard files on your desktop computer's hard disk. All information is stored in:

Documents and Settings\user\javame-sdk\3.0.5\work\emulator-instance\appdb\PIM

Each device instance has its own data. Lists are stored in subdirectories of the contacts, events, and todo directories. For example, a contact list called Contacts is contained in \appdb\PIM\Contacts:

Inside the list directory, items are stored in vCard (.vcs) or vCalendar (.vcf) format (see http://www.imc.org/pdi/). Contacts are stored in vCard format, while calendar and to-do items are both stored in vCalendar format.

16.3 Running PDAPDemo

PDAPDemo shows how to use the PIM and FileConnection APIs that are part of the JSR 75 specification.

16.3.1 Browsing Files

To run the file browser, you'll need to give the MIDlet appropriate security authorization, if you have not already done so. Right-click on your project, choose Properties, and select Specify the Security Domain. If necessary, select the maximum domain and press OK.

Now open and run the PDAPDemo project. Launch the FileBrowser MIDlet. You see a directory listing, and you can browse through the available directories and files. By default there is one directory, root1. This directory is located at:

Documents and Settings\user\javame-sdk\version\work\instance\appdb\filesystem\root1

Description of the illustration pdap-root1.gif

Select the directory and press the View soft button to enter it.

The directories photos and private are empty by default. You can add files and root directories and they will be visible to the JSR 75 File API. (This demo shows a README and some JPEGs that were added to the local photos directory.)

Description of the illustration pdap-dirs.gif

Using the Menu commands you can view a file or see its properties. Try selecting the file and choosing Properties or View from the menu.

16.3.2 The PIM API

The JSR75 PIM APIs example demonstrates how to access personal information, like contact lists, calendars, and to-do lists. After you launch the example, choose a type of list from the main menu.

In this example application, each type of list works the same way and each list type contains a single list. For example, if you choose Contact Lists, there is a single contact list called Contacts. Event Lists contains a single list called Events, and To Do Lists contains a single list named To Do.

Description of the illustration pdap-demo-listtype.gif

Once you've selected a list type and chosen the specific list, you can view all the items in the list. If this is the first time you've run the example, the list is probably empty.

To add an item, choose New from the menu. The application prompts you for a Formatted Name for the item. You can add more data fields to this item using option 3, Add Field, in the menu. You see a list of field names. Pick as many as you like. You can fill in the field at any time.

Description of the illustration pdap-demo-newcontact.gif

To save the list item, choose Commit (option 5) from the menu.

To return to the list, choose the Back command. You'll see the item you just created in the list.

The items that you create are stored in standard vCard or vCalendar format in the device\pim directory.

The PIM API allows for exporting contact, calender, and to-do items in a standard format. The exact format depends on the list type. When you are viewing an item in any list, the menu contains a command for viewing the exported item.

For example, when you are viewing a contact list item, the menu contains Show vCard. When you choose this command, the exported item is shown on the screen. Calendar items and to-do items both get exported as vCalendar.