Package javax.microedition.io.file

This package describes file system access support based on the Generic Connection Framework.

See:
Description

Interface Summary

FileConnection	This interface is intended to access files or directories that are located on removeable media and/or file systems on a device.
FileSystemListener	This class is used for receiving status notification when adding or removing a file system root.

Class Summary

FileSystemRegistry

The FileSystemRegistry is a central registry for file system listeners interested in adding and removing (or mounting and unmounting) the file systems on a device.

Exception Summary

ConnectionClosedException	Indicates that a method was invoked on a file connection but the connection is closed.
IllegalModeException	Indicates that a method was invoked that requires a particular security mode (such as READ or WRITE), but the open connection is not in the mode required.

Package javax.microedition.io.file Description

This package describes file system access support based on the Generic Connection Framework.

FileConnection URL Format

The format of the input string used to access a FileConnection through Connector.open() must follow the format for a fully qualified, absolute path file name as described in the file URL format in IETF RFCs 1738 and 2396. The RFCs dictate that a file URL takes the form:

file://<host>/<path>

In this form, <host> is the fully qualified domain name of the system on which the <path> is accessible, and <path> is a hierarchical directory path of the form <root>/<directory>/.../<name>.

The file connection defines the first directory as the root, which corresponds to a logical mount point for a particular storage unit or memory. Root strings are defined by the platform or implementation and can be a string of zero or more characters (the empty string "" can be a valid root string on some systems) followed by a trailing "/" to denote that the root is a directory. Each root string is guaranteed to uniquely refer to a root. Root names are device specific and are not required to adhere to any standard. Following are examples of possible root strings and how to open them:

Root Value	Opening a FileConnection to the Root
CFCard/	Connector.open("file:///CFCard/");
SDCard/	Connector.open("file:///SDCard/");
MemoryStick/	Connector.open("file:///MemoryStick/");
C:/	Connector.open("file:///C:/");
/	Connector.open("file:////");

The valid <root> values for a device can be retrieved by using the FileSystemRegistry.listRoots() method.

The file URL must be a full absolute path file name. Relative path names (names that contain ".." or ".") are not valid in the API except where explicitly noted.

URL Character Format

The Java class String is used to encapsulate the character string of a URI in the Connector.open() method. String is capable of containing Unicode characters and so the file URI can also be specified using Unicode characters.

However, RFC 2396 (used to define the file URI format) allows file URIs to be expressed using an escaped ASCII format. In this scheme, non-ASCII characters are encoded using UTF-8 and the resulting bytes are escaped using the "%hh" mechanism.

The generic escaping mechanism and valid character repertoire that can be presented literally are also defined in RFC 2396. This canonical form of the URI is referred to in this specification as escaped form. If the escaping mechanism is not present in the URI, the URI is said to be in unescaped form". Any occurrence of the percent character (%) indicates that the URI is in escaped form. To specify the percent character in a URI, the escaped character sequence of "%25" must be used.

All of the methods in the Connector class accept both escaped and unescaped forms of file URIs as valid file specifications. All methods in the FileConnection API that accepts any part of the file URI accepts both escaped and unescaped forms of the input parameter unless otherwise explicitly stated. All methods in the FileConnection API that return any part of the file URI return the values in unescaped form unless otherwise explicitly stated.

File Separator Specification

The FileConnection API returns and accepts only a forward slash (/) as a file separator in File URIs and directory names. However, a platform may use a different separator. This separator can be retrieved via the system property file.separator, which is defined to contain the path separator used in the given platform. When presenting directories or path names in user interfaces, applications should replace the trailing forward slash with the file.separator value.

File Stream Behavior

When a "file://" parameter is specified, the behavior of the methods Connector.openInputStream, Connector.openDataInputStream, Connector.openOutputStream, and Connector.openDataOutputStream is governed by the FileConnection methods of the same name. In other words, Connector.openXXXStream is equivalent to invoking FileConnection fs = Connector.open and then fs.openXXXStream.