This package describes file system access support based on the Generic Connection Framework.
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.
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.
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.
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.