PDAP Public Review Draft

javax.microedition.io
Interface FileConnection

All Superinterfaces:
Connection, InputConnection, OutputConnection, StreamConnection

public interface FileConnection
extends StreamConnection

This interface is intended to access files that are stored on removable media such as

Device internal filesystems in RAM or ROM may also be accessed through this class as well, provided there is underlying hardware and OS support. If file connections are not supported to a particular media or file system, attempts to open a file connection to the media or file system through Connector.open() will result in an javax.microedition.io.IOException being thrown.

Establishing a Connection

The format of the Connector.open() input string used to access a FileConnection must follow the format 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. The root of a file system supporting only one card reader may return the contents of the card directly. If more than one card reader is supported or the device supports a file system in RAM, the root strings are device specific. Since the roots are part of the path string as a directory, they have a trailing "/". Examples of possible root strings include:

   CFCard/
   SDCard/
   MemoryStick/
   C:/
   /
 

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

A single connection object only references a single file or directory.  A connection object cannot be changed dynamically to refer to a different file or directory than originally connected to. To reference a different file or directory, a completely separate connection must be established through the Connector.open() method.

Connection Behavior

The file connection API is different from other Generic Connection Framework APIs in that a connection object can be successfully returned from the Connector.open() method without actually referencing an existing file or directory. This method is used to allow the creation of new files and directories on a file system. For example, the following code can be used to create a new file on a file system:

 try {
     FileConnection fconn = (FileConnection)Connector.open("file:///CFCard/newfile.txt");
     // If no exception is thrown, then the URI is valid, but the file may or may not exist.
     if (!fconn.exists())    
         fconn.create();  // create the file if it doesn't exist
 
     fconn.close();
 }
 catch (IOException ioe) {
 }

Developers should always check for the file's or directory's existence after a connection is established to determine if the file or directory actually exists. Similarly, files or directories can be deleted using the delete() method, and developers should close the connection immediately after deletion to prevent exceptions from accessing a connection to a non-existent file or directory.

Security

Access to file connections is restricted to prevent unauthorized manipulation of data. The security model applied to the file connection is defined by the implementing profile. The security model may be applied on the invocation of the Connector.open() method with a valid file connection string. Should the application not be granted access to the file system through the profile authorization scheme, a java.lang.SecurityException will be thrown from the Connector.open() method. The security model MAY be also applied during execution, specifically when the methods openInputStream(), openDataInputStream(), openOutputStream(), and openDataOutputStream() are invoked.

File access through the File Connection API is also restricted in order to protect the users files and data from both malicious and unintentional access. Implementations must not allow a File Connection to access RMS databases. Implementations should not allow access to files that are private to another application, system configuration files, and device and OS specific files.

Since:
PDAP 1.0
See Also:
FileSystemRegistry

Method Summary
 long availableSize()
          This method is used to determine the free memory that is available on the fileystem.
 boolean canRead()
          This method is used to check if the selected file is readable.
 boolean canWrite()
          This method is used to check if the selected file is writable.
 boolean create()
          This method is used to create a file that is specified in the Connector.open() method.
 boolean delete()
          This method is used to delete a file/dir specified in the Connector.open() URL.
 long directorySize(boolean includeSubDirs)
          This method is used to determine the size in bytes that is used by a directory.
 boolean exists()
          This method is used to check if the file/dir specified in the URL passed to the Connector.open() method exists.
 long fileSize()
          This method is invoked to determine the size of a selected file.
 java.lang.String getPath()
          This method is used to return the path excluding the "file" scheme and host from where the file/directory specified in the Connector.open() method is opened.
 java.lang.String getURL()
          This method is used to return the full file URL including the scheme, host, and path from where the file/directory specified in the Connector.open() method is opened.
 boolean isDirectory()
          This method is used to check if the URL passed to the Connector.open() is a directory.
 boolean isHidden()
          This method is used to check if the selected file is hidden.
 long lastModified()
          Returns the time that the file denoted by the URL specified in the Connector.open() method was last modified.
 java.lang.String[] list()
          This method is used to get a list of all files contained in a directory.
 boolean mkdir()
          This method is used to create a directory that is specified in the Connector.open() method.
 boolean rename(java.lang.String newName)
          Rename the selected dir/file to a new name.
 void setHidden(boolean tf)
          This method is used to set the selected file hidden.
 void setReadable(boolean tf)
          This method is used to set the selected file readable.
 void setWriteable(boolean tf)
          This method is used to set the selected file writable.
 long totalSize()
          This method is used to determine the total size of the filesystem.
 long usedSize()
          This method is used to determine the used memory of a file system.
 
Methods inherited from interface javax.microedition.io.InputConnection
openDataInputStream, openInputStream
 
Methods inherited from interface javax.microedition.io.Connection
close
 
Methods inherited from interface javax.microedition.io.OutputConnection
openDataOutputStream, openOutputStream
 

Method Detail

totalSize

public long totalSize()
This method is used to determine the total size of the filesystem.
Returns:
The total size of the filesystem in bytes, e.g. a removable card.

availableSize

public long availableSize()
This method is used to determine the free memory that is available on the fileystem.
Returns:
The available size of bytes on a file system.

usedSize

public long usedSize()
This method is used to determine the used memory of a file system.
Returns:
The used size of bytes on a file system.

directorySize

public long directorySize(boolean includeSubDirs)
                   throws IOException
This method is used to determine the size in bytes that is used by a directory.
Parameters:
includeSubdirs - If set to true, the method will determine the size of the given directory and all subdirs recursivly. If false, the method returns the size of the files in the directory only.
Returns:
The size in bytes occupied by the files incuded in the directory.
Throws:
IOException - if the method is invoked on a file.

fileSize

public long fileSize()
              throws IOException
This method is invoked to determine the size of a selected file.
Returns:
The size in bytes of the selected file.
Throws:
IOException - if the method is invoked on a directory.

canRead

public boolean canRead()
                throws IOException
This method is used to check if the selected file is readable.
Returns:
True if the file is readable otherwise false.
Throws:
IOException - if the method is invoked on a directory.
See Also:
setReadable(boolean)

canWrite

public boolean canWrite()
                 throws IOException
This method is used to check if the selected file is writable.
Returns:
True if the file is writeable otherwise false.
Throws:
IOException - if the method is invoked on a directory.
See Also:
setWriteable(boolean)

isHidden

public boolean isHidden()
                 throws IOException
This method is used to check if the selected file is hidden.
Returns:
True if the file is hidden otherwise false.
Throws:
IOException - if the method is invoked on a directory.
See Also:
setHidden(boolean)

setReadable

public void setReadable(boolean tf)
                 throws IOException
This method is used to set the selected file readable.
Parameters:
tf - The new state of the readable flag of the selected file.
Throws:
IOException - if the method is invoked on a directory.
SecurityException - if the security is set to readonly for accessing FileConnections.
See Also:
canRead()

setWriteable

public void setWriteable(boolean tf)
                  throws IOException
This method is used to set the selected file writable.
Parameters:
tf - The new state of the writable flag of the selected file.
Throws:
IOException - if the method is invoked on a directory.
SecurityException - if the security is set to readonly for accessing FileConnections.
See Also:
canWrite()

setHidden

public void setHidden(boolean tf)
               throws IOException
This method is used to set the selected file hidden.
Parameters:
tf - The new state of the hidden flag of the selected file.
Throws:
IOException - if the method is invoked on a directory.
SecurityException - if the security is set to readonly for accessing FileConnections.
See Also:
isHidden()

list

public java.lang.String[] list()
This method is used to get a list of all files contained in a directory.
Returns:
An array of pathnames denoting the files and directories in the directory. Directories are denoted with a trailing slash "/" in their returned name. The array will be empty if the directory is empty. Returns null if this pathname does not denote a directory, or an IO error occurs.

create

public boolean create()
This method is used to create a file that is specified in the Connector.open() method.
Returns:
True if the file has been successfully created otherwise false.
Throws:
SecurityException - if the security is set to readonly for accessing FileConnections.

mkdir

public boolean mkdir()
This method is used to create a directory that is specified in the Connector.open() method. The URL needs to end with a trailing "/" in order for a directory to be created.
Returns:
True if the directory has been successfully created otherwise false.
Throws:
SecurityException - if the security is set to readonly for accessing FileConnections.

exists

public boolean exists()
This method is used to check if the file/dir specified in the URL passed to the Connector.open() method exists.
Returns:
True if the specified file/dir exists otherwise false.

isDirectory

public boolean isDirectory()
This method is used to check if the URL passed to the Connector.open() is a directory.
Returns:
True if the specified URL is a directory otherwise false.

delete

public boolean delete()
This method is used to delete a file/dir specified in the Connector.open() URL.
Returns:
True if the file/dir has been successfully deleted otherwise or in case of anerror false.
Throws:
SecurityException - if the security is set to readonly for accessing FileConnections.

rename

public boolean rename(java.lang.String newName)
Rename the selected dir/file to a new name.
Returns:
True if the file/directory has been successfully renamed otherwise or in case of an error false.
Throws:
SecurityException - if the security is set to readonly for accessing FileConnections.

getPath

public java.lang.String getPath()
This method is used to return the path excluding the "file" scheme and host from where the file/directory specified in the Connector.open() method is opened. The resulting String looks as follows:
   /<root>/<directory>/<filename.extension>
 
or
   /<root>/<directory>/<directoryname>/
 

getURL

public java.lang.String getURL()
This method is used to return the full file URL including the scheme, host, and path from where the file/directory specified in the Connector.open() method is opened. The resulting String looks as follows:
   file://<host>/<root>/<directory>/<filename.extension>
 
or
   file://<host>/<root>/<directory>/<directoryname>/
 

lastModified

public long lastModified()
Returns the time that the file denoted by the URL specified in the Connector.open() method was last modified.

PDAP 1.0 Spec, Rev. 0.16