Print-friendly Version

New J2ME developers are often surprised to discover that the Connected Limited Device Configuration (CLDC) and the profiles based on it are not required to support the reading or writing of files. The Generic Connection Framework (GCF) defined by the CLDC does provide the basic scaffolding for file I/O, primarily through the InputConnection, OutputConnection, and StreamConnection interfaces, but it's up to specific implementations to expose this capability to applications. This limitation isn't a bad thing: It allows the CLDC to be ported to devices without a file system. (Such devices are more popular than you might think: devices running Palm OS, for example, do not support file systems in main memory, only on memory expansion cards.) If a file system is supported, however, it would be nice to have a standard way of using it through the GCF. This is the purpose of the File Connection Optional Package.

The File Connection Optional Package (FCOP) is one of two optional packages defined by JSR 75 through the Java Community Process. The other, the PIM Optional Package, is discussed in another tech tip. Because the FCOP specification is still a draft standard and no reference implementation is yet available, the information presented here is still subject to change.

If you're not familiar with optional packages, see the article "J2ME Optional Packages" for details on how they work. Simply put, an optional package is a set of programming interfaces that can be added to a J2ME profile or configuration to provide a category of functionality that some users of that configuration or profile will need but not all. FCOP can be supported on any J2ME platform, because it depends only on the core classes defined by the CLDC, and thus included in the Connected Device Configuration (CDC) as well.

You can write applications that use FCOP in two ways. If all you want to do is read files, you can use the "file:" URL prefix to obtain an InputConnection interface to a file. For example:

... import javax.microedition.io.*; String url = "file:///data.txt"; InputConnection conn = null; int mode = Connector.READ_ONLY; try { conn =(InputConnection) Connector.open( url, mode ); } catch( IOException ioe ){ // no file } ...

This code can be used on any platform that exposes the file system through the GCF, whether it supports FCOP or not. The Connected Device Configuration (CDC) and the profiles based on it all support this method of reading files, for example. Such a platform may also allow writing to files if you specify the Connector.READ_WRITE or Connector.WRITE_ONLY mode, returning a StreamConnection or an OutputConnection as appropriate.

The second way to use FCOP is through the new FileConnection interface. Before doing so, however, an application should ensure that FCOP is available, by checking for the presence of the microedition.io.file.FileConnection.version property:

... // Check that the File Connection Optional Package is there String v = System.getProperty( "microedition.io.file.FileConnection.version" ); if( v != null ){ // FCOP available } else { // FCOP not available } ...

The value of the property is the version number of FCOP, which for the first release is "1.0".

When FCOP is supported, all GCF connections made using the "file:" protocol return an instance of javax.microedition.io.file.FileConnection. FileConnection extends StreamConnection by adding methods for file and directory manipulation. The added functionality is similar to that available in J2SE's java.io.File class. The general format for opening a file is a URL of the form:

This is the format defined in Section 3.10 of RFC 1738, the document that defines the general format of a URL. Devices are unlikely to support file access across a network, so in almost every case the URL will refer to the local host, and the host part of the URL is commonly omitted. What's left, then, is the path part, consisting of a root (identifying the root directory of a mounted file system) and a file or directory path. On a Windows platform, for example, a valid URL might be:

On a device with memory expansion slots the URL might look like this:

Because the number and names of mounted file systems vary from device to device, a support class is provided that lets applications list the available file systems. This FileSystemRegistry class (defined in the javax.microedition.io.file package) also notifies interested applications whenever the user inserts or removes a memory expansion card from the device.

The file URL passed to Connector.open() normally refers to an existing file or directory. For example, here's how to obtain the list of files in a directory:

... String url = "file:///SDCard"; FileConnection conn = null; try { conn = (FileConnection) Connector.open( url ); if( conn.isDirectory() ){ Enumeration names = conn.list(); while( names.hasMoreElements() ){ String name = (String) e.nextElement(); // do something } } else { // not a directory! } } catch( IOException e ){ // could not access the URL } catch( SecurityException e ){ // no permission to read the directory } ...

The URL can also refer to files or directories that don't yet exist. You can create a file using FileConnection.create(), for example:

... String url = "file:///SDCard/myfile.txt"; FileConnection conn = null; try { conn = (FileConnection) Connector.open( url, Connector.WRITE_ONLY ); if( conn.create() ){ // create the file OutputStream out = conn.openOutputStream(); // now write data to the file } conn.close(); } catch( IOException e ){ // error } catch( SecurityException e ){ // no permission to create/write } ...

Note that almost every method in the FileConnection class has the potential to throw a SecurityException. The FCOP specification does not define a specific security model for controlling access to the file system, leaving that task to the configuration or profile that incorporates FCOP.

We've only touched on a few aspects of FCOP. For full details, check out the Javadoc for the FCOP classes.