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 the adding and removing (or mounting and unmounting) of file systems on a device.

Exception Summary

ConnectionClosedException	Represents an exception thrown when a method is invoked on a file connection but the method cannot be completed because the connection is closed.
IllegalModeException	Represents an exception thrown when a method is invoked requiring a particular security mode (e.g.

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 as part of IETF RFCs 1738 & 2396. That RFC dictates that a file URL takes the form:

file://<host>/<path>

In the form above, <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>/<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. Examples of possible root strings include: Examples of possible root strings and how to open them include:

Possible 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 (i.e. names that contain ".." or ".") are not valid in the API except where explicitly noted.

URL Character Format

The Java class String is to encapsulate the character string of a URI in the Connector.open() method. The Java String class is capable of containing Unicode characters and therefore the file URI may 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 defined in the URI specification [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 character "%" indicates that the URI provided 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 "/" 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. Applications should replace the trailing "/" with the file.separator value when presenting directories or path names in user interfaces.

File Stream Behavior

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