Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| IM Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.siemens.icm.io.file
Interface FileConnection

All Superinterfaces:
  Connection, InputConnection, OutputConnection, StreamConnection

public interface FileConnection
extends StreamConnection

This interface is intended to access files or directories that are located on removeable media and/or file systems on a device.

Device internal filesystems in memory 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()` results in an `javax.microedition.io.IOException` being thrown.

## Establishing a Connection

The format of the input string used to access a FileConnection through `Connector.open()` must follow the format of a fully-qualified, absolute path file name as described by the file URL format in IETF RFCs 1738 & 2396. Further detail for the File URL format can be found in the com.siemens.mp.microedition.io.file package description.

A single connection object only references a single file or directory at a time. In some cases, a connection object can be reused to refer to a different file or directory than it was originally associated with (see `setFileConnection(java.lang.String)`). In general, the best approach to reference a different file or directory is by establishing a completely separate connection through the `Connector.open()` method.

## FileConnection Behavior

File connection is different from other Generic Connection Framework connections in that a connection object can be successfully returned from the `Connector.open()` method without actually referencing an existing entity (in this case, a file or directory). This behavior allows 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, where CFCard is a valid existing file system root name for a given implementation:

`

     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.

A file connection's open status is unaffected by the opening and closing of input and output streams from the file connection; the file connection stays open until `close()` is invoked on the FileConnection instance. Input and output streams may be opened and closed multiple times on a FileConnection instance.

All `FileConnection` instances have one underlying `InputStream` and one `OutputStream`. Opening a `DataInputStream` counts as opening an `InputStream,` and opening a `DataOutputStream` counts as opening an `OutputStream`. A `FileConnection` instance can have only one `InputStream` and one `OutputStream` open at any one time. Trying to open more than one `InputStream` or more than one `OutputStream` from a `StreamConnection` causes an `IOException`. Trying to open an `InputStream` or an `OutputStream` after the `FileConnection` has been closed causes an `IOException`. The skip methode of the `InputStream` on a `FileConnection` does not skip the bytes from the current position. It skips the bytes from the begin of the stream.

The inherited `StreamConnection` methods in a `FileConnection` instance are not synchronized. The only stream method that can be called safely from another thread is `close`. When `close` is invoked on a stream that is executing in another thread, any pending I/O method MUST throw an `InterruptedIOException`. In the above case, implementations SHOULD try to throw the exception in a timely manner. When all open streams have been closed, and when the `FileConnection` is closed, any pending I/O operations MUST be interrupted in a timely manner.

Data written to the output streams of these `FileConnection` objects is not guaranteed to be flushed to the stream's destination (and subsequently made available to any input streams) until either `flush()` or `close()` is invoked on the stream.

## Security

Access to file connections is restricted to prevent unauthorized manipulation of data. The access security model applied to the file connection is defined by the implementing profile. The security model is applied on the invocation of the `Connector.open()` method with a valid file connection string. The mode provided in the `open()` method (`Connector.READ_WRITE` by default) indicates the application's request for access rights for the indicated file or directory and is therefore checked against the security scheme. All three connections modes (`READ_WRITE, WRITE_ONLY,` and `READ_ONLY`) are supported for a file connection and determine the access requested from the security model.

The security model is also applied during use of the returned FileConnection, specifically when the methods `openInputStream()`, `openDataInputStream()`, `openOutputStream()`, and `openDataOutputStream()` are invoked. These methods have implied request for access rights (i.e. input stream access is requesting read access, and output stream access is requesting write access). Should the application not be granted the appropriate read or write access to the file or file system by the profile authorization scheme, a `java.lang.SecurityException` is thrown.

File access through the File Connection API may be restricted to files that are within a public context and not deemed private or sensitive. This restriction is intended to protect the device's and other users' files and data from both malicious and unintentional access. RMS databases cannot be accessed using the File Connection API. Access to files and directories that are private to another application, files and directories that are private to a different user than the current user, system configuration files, and device and OS specific files and directories may be restricted. In these situations, a `java.lang.SecurityException` is thrown from the `Connector.open()` method if the file, file system, or directory is not allowed to be accessed.

## Permissions

Permissions are the MIDP 2.0 mechanism by which a MIDlet may request security access to protected APIs or functions. A MIDlet can request access by including the permissions in the `MIDlet-Permissions` and `MIDlet-Permissions-Opt` attributes in its JAD or manifest. Table 1 defines the permissions applicable to the FileConnection APIs, and the API methods that are protected by those permissions:

Table 1: FileConnection Permissions and Protected Methods

Permission | Protected API Calls
--- | ---
`javax.microedition.io.Connector.file.read` | `com.siemens.mp.microedition.io.Connector` methods: `` `open("file://...")``open("file://...", Connector.READ) open("file://...", Connector.READ_WRITE) openDataInputStream("file://...") openInputStream("file://...")` `com.siemens.mp.microedition.io.file.FileConnection` methods: `setFileConnection`, when instance opened with READ `setFileConnection`, when instance opened with READ_WRITE `com.siemens.mp.microedition.io.file.FileSystemRegistry` methods: `addFileSystemListener listRoots`
`javax.microedition.io.Connector.file.write` | `com.siemens.mp.microedition.io.Connector` methods: `` `open("file://...")``open("file://...", Connector.WRITE) open("file://...", Connector.READ_WRITE) openDataOutputStream("file://...") openOutputStream("file://...")` `com.siemens.mp.microedition.io.file.FileConnection` methods: `setFileConnection`, when instance opened with WRITE `setFileConnection`, when instance opened with READ_WRITE

Note that the following protected API calls from the Table 1 require both `read` and `write` permissions:

> `Connector.open("file://...")
> Connector.open("file://...", Connector.READ_WRITE)
> FileConnection.setFileConnection("file://...")` if the FileConnection instance is opened in READ_WRITE

## Permission Scope

It should be noted that the permissions protect API calls, regardless of the data that is being accessed. For example, a successful grant of READ_WRITE access to the `Connector.open("file://...")` method allows the application to read/write any file or directory, not just the file/directory used as the method's parameter. The parameters of the API calls (which indicate the data being accessed) is not a factor at all in the granting of the permissions, as dictated by MIDP 2.0 security definitions. For this reason, it is recommended that a user interaction mode of "one-shot" be used when user authorization is required so that the user is notified on every instance that a file or directory is accessed.

Since:
  FileConnection 1.0
See Also:
  `FileSystemRegistry`

Method Summary
`long` | `availableSize()` Determines the free memory that is available on the file system the file or directory resides on.
`boolean` | `canRead()` Checks if the file or directory is readable.
`boolean` | `canWrite()` Checks if the file or directory is writable.
`void` | `create()` Creates a file corresponding to the file string provided in the Connector.open() method for this FileConnection.
`void` | `delete()` Deletes the file or directory specified in the Connector.open() URL.
`long` | `directorySize(boolean includeSubDirs)` Determines the size in bytes on a file system of all of the files that are contained in a directory.
`boolean` | `exists()` Checks if the file or directory specified in the URL passed to the Connector.open() method exists.
`long` | `fileSize()` Determines the size of a file on the file system.
`String` | `getName()` Returns the name of a file or directory excluding the URL schema and all paths.
`String` | `getPath()` Returns the path excluding the file or directory name and the "file" URL schema and host from where the file or directory specified in the Connector.open() method is opened.
`String` | `getURL()` Returns the full file URL including the scheme, host, and path from where the file or directory specified in the Connector.open() method is opened.
`boolean` | `isDirectory()` Checks if the URL passed to the Connector.open() is a directory.
`boolean` | `isHidden()` Checks if the file is hidden.
`boolean` | `isOpen()` Returns an indication of whether the file connection is currently open or not.
`long` | `lastModified()` Returns the time that the file denoted by the URL specified in the Connector.open() method was last modified.
`Enumeration` | `list()` Gets a list of all files and directories contained in a directory.
`Enumeration` | `list(String filter, boolean includeHidden)` Gets a filtered list of files and directories contained in a directory.
`void` | `mkdir()` Creates a directory corresponding to the directory string provided in the Connector.open() method.
`DataInputStream` | `openDataInputStream()` Open and return a data input stream for a connection.
`DataOutputStream` | `openDataOutputStream()` Open and return a data output stream for a connection.
`InputStream` | `openInputStream()` Open and return an input stream for a connection.
`OutputStream` | `openOutputStream()` Open and return an output stream for a connection.
`OutputStream` | `openOutputStream(long byteOffset)` This method opens an output stream and positions it at the indicated byte offset in the file.
`void` | `rename(String newName)` Renames the selected file or directory to a new name in the same directory.
`void` | `setFileConnection(String fileName)` Resets this FileConnection object to another file or directory.
`void` | `setHidden(boolean hidden)` Sets the hidden attribute of the selected file to the value provided.
`void` | `setReadable(boolean readable)` Sets the file or directory readable attribute to the indicated value.
`void` | `setWritable(boolean writable)` Sets the selected file or directory writable attribute to the indicated value.
`long` | `totalSize()` Determines the total size of the file system the connection's target resides on.
`void` | `truncate(long byteOffset)` Truncates the file, discarding all data from the given byte offset to the current end of the file.
`long` | `usedSize()` Determines the used memory of a file system the connection's target resides on.

Methods inherited from interface javax.microedition.io.Connection
`close`

Method Detail

### isOpen

    public boolean isOpen()

  Returns an indication of whether the file connection is currently open or not.

  Returns:
    true if the file connection is open, false otherwise.

### openInputStream

    public InputStream openInputStream()
                                throws IOException

  Open and return an input stream for a connection. The connection's target must already exist and be accessible for the input stream to be created.

  Specified by:
    `openInputStream` in interface `InputConnection`
  Returns:
    An open input stream
  Throws:
    `IOException` - if an I/O error occurs, if the method is invoked on a directory, if the connection's target does not yet exist, or the connection's target is not accessible.
    `IllegalModeException` - if the application does have read access to the connection's target but has opened the connection in `Connector.WRITE` mode.
    `SecurityException` - If the application is not granted read access to the connection's target.

### openDataInputStream

    public DataInputStream openDataInputStream()
                                        throws IOException

  Open and return a data input stream for a connection. The connection's target must already exist and be accessible for the input stream to be created.

  Specified by:
    `openDataInputStream` in interface `InputConnection`
  Returns:
    An open input stream
  Throws:
    `IOException` - If an I/O error occurs, if the method is invoked on a directory, if the connection's target does not yet exist, or the connection's target is not accessible.
    `IllegalModeException` - if the application does have read access to the connection's target but has opened the connection in `Connector.WRITE` mode.
    `SecurityException` - If the application is not granted read access to the connection's target.

### openOutputStream

    public OutputStream openOutputStream()
                                  throws IOException

  Open and return an output stream for a connection. The output stream is positioned at the start of the file. Writing data to the output stream overwrites the contents of the files (i.e. does not insert data). Writing data to output streams beyond the current end of file automatically extends the file size. The connection's target must already exist and be accessible for the output stream to be created. `openOutputStream(long)` should be used to position an output stream to a different position in the file.

  Changes made to a file through an output stream may not be immediately made to the actual file residing on the file system because platform and implementation specific use of caching and buffering of the data. Steam contents and file length extensions are not necessarily visible outside of the application immediately unless `flush()` is called on the stream. The returned output stream is automatically and synchronously flushed when it is closed.

  Specified by:
    `openOutputStream` in interface `OutputConnection`
  Returns:
    An open output stream
  Throws:
    `IOException` - If an I/O error occurs, if the method is invoked on a directory, the file does not yet exist, or the connection's target is not accessible.
    `IllegalModeException` - if the application does have write access to the connection's target but has opened the connection in `Connector.READ` mode.
    `SecurityException` - If the application is not granted write access to the connection's target.
  See Also:
    `openOutputStream(long)`

### openDataOutputStream

    public DataOutputStream openDataOutputStream()
                                          throws IOException

  Open and return a data output stream for a connection. The output stream is positioned at the start of the file. Writing data to the output stream overwrites the contents of the files (i.e. does not insert data). Writing data to output streams beyond the current end of file automatically extends the file size. The connection's target must already exist and be accessible for the output stream to be created. `openOutputStream(long)` should be used to position an output stream to a different position in the file.

  Changes made to a file through an output stream may not be immediately made to the actual file residing on the file system because platform and implementation specific use of caching and buffering of the data. Steam contents and file length extensions are not necessarily visible outside of the application immediately unless `flush()` is called on the stream. The returned output stream is automatically and synchronously flushed when it is closed.

  Specified by:
    `openDataOutputStream` in interface `OutputConnection`
  Returns:
    An open output stream
  Throws:
    `IOException` - If an I/O error occurs, if the method is invoked on a directory, the file does not yet exist, or the connection's target is not accessible.
    `IllegalModeException` - if the application does have write access to the connection's target but has opened the connection in `Connector.READ` mode.
    `SecurityException` - If the application is not granted write access to the connection's target.
  See Also:
    `openOutputStream(long)`

### openOutputStream

    public OutputStream openOutputStream(long byteOffset)
                                  throws IOException

  This method opens an output stream and positions it at the indicated byte offset in the file. Data written to the returned output stream at that position overwrites any existing data until EOF is reached, and then additional data is appended. The connection's target must already exist and be accessible for the output stream to be created.

  Changes made to a file through an output stream may not be immediately made to the actual file residing on the file system because platform and implementation specific use of caching and buffering of the data. Steam contents and file length extensions are not necessarily visible outside of the application immediately unless `flush()` is called on the stream. The returned output stream is automatically and synchronously flushed when it is closed.

  Parameters:
    `byteOffset` - number of bytes to skip over from the beginning of the file when positioning the start of the OutputStream. If the provided offset is larger than or equal to the current file size, the OutputStream is positioned at the current end of the file for appending.
  Returns:
    an open OutputStream positioned at the byte offset in the file, or the end of the file if the offset is greater than the size of the file.
  Throws:
    `IOException` - If an I/O error occurs, if the method is invoked on a directory, the file does not yet exist, or the connection's target is not accessible.
    `IllegalModeException` - if the application does have write access to the connection's target but has opened the connection in `Connector.READ` mode.
    `SecurityException` - if the security if the application does not allow write access to the file.
    `IllegalArgumentException` - if byteOffset has a negative value.

### totalSize

    public long totalSize()

  Determines the total size of the file system the connection's target resides on.

  Returns:
    The total size of the file system in bytes, or -1 if the file system is not accessible.
  Throws:
    `SecurityException` - if the security of the application does not have read access to the root volume.
    `IllegalModeException` - if the application does have read access to the connection's target but has opened the connection in `Connector.WRITE` mode.
    `ConnectionClosedException` - if the connection is closed.

### availableSize

    public long availableSize()

  Determines the free memory that is available on the file system the file or directory resides on. This may only be an estimate and may vary based on platform-specific file system blocking and metadata information.

  Returns:
    The available size in bytes on a file system, or -1 if the file system is not accessible.
  Throws:
    `SecurityException` - if the security of the application does not have read access to the root volume.
    `IllegalModeException` - if the application does have read access to the directory but has opened the connection in `Connector.WRITE` mode.
    `ConnectionClosedException` - if the connection is closed.

### usedSize

    public long usedSize()

  Determines the used memory of a file system the connection's target resides on. This may only be an estimate and may vary based on platform-specific file system blocking and metadata information.

  Returns:
    The used size of bytes on a file system, or -1 if the file system is not accessible.
  Throws:
    `SecurityException` - if the security of the application does not have read access to the root volume.
    `IllegalModeException` - if the application does have read access to the directory but has opened the connection in `Connector.WRITE` mode.
    `ConnectionClosedException` - if the connection is closed.

### directorySize

    public long directorySize(boolean includeSubDirs)
                       throws IOException

  Determines the size in bytes on a file system of all of the files that are contained in a directory.

  Parameters:
    `includeSubDirs` - If set to true, the method determines the size of the given directory and all subdirs recursively. If false, the method returns the size of the files in the directory only.
  Returns:
    The size in bytes occupied by the files included in the directory, or -1 if the directory does not exist or is not accessible.
  Throws:
    `IOException` - if the method is invoked on a file.
    `SecurityException` - if the security of the application does not have read access for the directory.
    `IllegalModeException` - if the application does have read access to the directory but has opened the connection in `Connector.WRITE` mode.
    `ConnectionClosedException` - if the connection is closed.

### fileSize

    public long fileSize()
                  throws IOException

  Determines the size of a file on the file system. The size of a file always represents the number of bytes contained in the file; there is no pre-allocated but empty space in a file.

  `fileSize()` always returns size of the file on the file system, and not in any pending output stream. `flush()` should be used before calling `fileSize()` to ensure the contents of the output streams opened to the file get written to the file system.

  Returns:
    The size in bytes of the selected file, or -1 if the file does not exist or is not accessible.
  Throws:
    `IOException` - if the method is invoked on a directory.
    `SecurityException` - if the security of the application does not have read access for the file.
    `IllegalModeException` - if the application does have read access to the file but has opened the connection in `Connector.WRITE` mode.
    `ConnectionClosedException` - if the connection is closed.

### canRead

    public boolean canRead()

  Checks if the file or directory is readable. This method checks the attributes associated with a file or directory by the underlying file system. Some file systems may not support associating attributes with a file, in which case this method returns true.

  Returns:
    true if the connection's target exists, is accessible, and is readable, otherwise false.
  Throws:
    `SecurityException` - if the security of the application does not have read access for the connection's target.
    `IllegalModeException` - if the application does have read access to the connection's target but has opened the connection in `Connector.WRITE` mode.
    `ConnectionClosedException` - if the connection is closed.
  See Also:
    `setReadable(boolean)`

### canWrite

    public boolean canWrite()

  Checks if the file or directory is writable. This method checks the attributes associated with a file or directory by the underlying file system. Some file systems may not support associating attributes with a file, in which case this method returns true.

  Returns:
    true if the connection's target exists, is accessible, and is writable, otherwise false.
  Throws:
    `SecurityException` - if the security of the application does not have read access for the connection's target.
    `IllegalModeException` - if the application does have read access to the connection's target but has opened the connection in `Connector.WRITE` mode.
    `ConnectionClosedException` - if the connection is closed.
  See Also:
    `setWritable(boolean)`

### isHidden

    public boolean isHidden()

  Checks if the file is hidden. The exact definition of hidden is system-dependent. For example, on UNIX systems a file is considered to be hidden if its name begins with a period character ('.'). On Win32 and FAT file systems, a file is considered to be hidden if it has been marked as such in the file's attributes. If hidden files are not supported on the referenced file system, this method always returns false.

  Returns:
    true if the file exists, is accessible, and is hidden, otherwise false.
  Throws:
    `ConnectionClosedException` - if the connection is closed.
    `SecurityException` - if the security of the application does not have read access for the connection's target.
    `IllegalModeException` - if the application does have read access to the connection's target but has opened the connection in `Connector.WRITE` mode.
  See Also:
    `setHidden(boolean)`

### setReadable

    public void setReadable(boolean readable)
                     throws IOException

  Sets the file or directory readable attribute to the indicated value. The readable attribute for the file on the actual file system is set immediately upon invocation of this method. If the file system doesn't support a settable read attribute, this method is ignored and `canRead()` always returns true.

  Parameters:
    `readable` - The new state of the readable flag of the selected file.
  Throws:
    `IOException` - of the connection's target does not exist or is not accessible.
    `ConnectionClosedException` - if the connection is closed.
    `SecurityException` - if the security of the application does not have write access to the connection's target.
    `IllegalModeException` - if the application does have write access to the connection's target but has opened the connection in `Connector.READ` mode.
  See Also:
    `canRead()`

### setWritable

    public void setWritable(boolean writable)
                     throws IOException

  Sets the selected file or directory writable attribute to the indicated value. The writable attribute for the file on the actual file system is set immediately upon invocation of the method. If the file system doesn't support a settable write attribute, this method is ignored and `canWrite()` always returns true.

  Parameters:
    `writable` - The new state of the writable flag of the selected file.
  Throws:
    `IOException` - if the connection's target does not exist or is not accessible.
    `ConnectionClosedException` - if the connection is closed.
    `SecurityException` - if the security of the application does not have write access to the connection's target.
    `IllegalModeException` - if the application does have write access to the connection's target but has opened the connection in `Connector.READ` mode.
  See Also:
    `canWrite()`

### setHidden

    public void setHidden(boolean hidden)
                   throws IOException

  Sets the hidden attribute of the selected file to the value provided. The attribute is applied to the file on the actual file system immediately upon invocation of this method if the file system and platform support it. If the file system doesn't support a hidden attribute, this method is ignored and `isHidden()` always returns false. Since the exact definition of hidden is system-dependent, this method only works on file systems that support a settable file attribute. For example, on Win32 and FAT file systems, a file may be considered hidden if it has been marked as such in the file's attributes; therefore this method is applicable. However on UNIX systems a file may be considered to be hidden if its name begins with a period character ('.'). In the UNIX case, this method may be ignored and the method to make a file hidden may be the `rename()` method.

  Parameters:
    `hidden` - The new state of the hidden flag of the selected file.
  Throws:
    `IOException` - if the connection's target does not exist or is not accessible.
    `ConnectionClosedException` - if the connection is closed.
    `SecurityException` - if the security of the application does not have write access to the connection's target.
    `IllegalModeException` - if the application does have write access to the connection's target but has opened the connection in `Connector.READ` mode.
  See Also:
    `isHidden()`

### list

    public Enumeration list()
                     throws IOException

  Gets a list of all files and directories contained in a directory. The directory is the connection's target as specified in `Connector.open()`.

  Returns:
    An Enumeration of strings, denoting the files and directories in the directory. The string returned contain only the file or directory name and does not contain any path prefix (to get a complete path for each file or directory, prepend `getPath()`). Directories are denoted with a trailing slash "/" in their returned name. The Enumeration has zero length if the directory is empty. Any hidden files and directories in the directory are not included in the returned list. Any current directory indication (".") and any parent directory indication ("..") is not included in the list of files and directories returned.
  Throws:
    `IOException` - if invoked on a file, the directory does not exist, the directory is not accessible, or an I/O error occurs.
    `ConnectionClosedException` - if the connection is closed.
    `SecurityException` - if the security of the application does not have read access for the directory.
    `IllegalModeException` - if the application does have read access to the directory but has opened the connection in `Connector.WRITE` mode.

### list

    public Enumeration list(String filter,
                            boolean includeHidden)
                     throws IOException

  Gets a filtered list of files and directories contained in a directory. The directory is the connection's target as specified in `Connector.open()`.

  Parameters:
    `filter` - String against which all files and directories are matched for retrieval. An asterisk ("*") can be used as a wildcard to represent 0 or more occurrences of any character.
    `includeHidden` - boolean indicating whether files marked as hidden should be included or not in the list of files and directories returned.
  Returns:
    An Enumeration of strings, denoting the files and directories in the directory matching the filter. Directories are denoted with a trailing slash "/" in their returned name. The Enumeration has zero length if the directory is empty or no files and/or directories are found matching the given filter. Any current directory indication (".") and any parent directory indication ("..") is not included in the list of files and directories returned.
  Throws:
    `IOException` - if invoked on a file, the directory does not exist, the directory is not accessible, or an I/O error occurs.
    `ConnectionClosedException` - if the connection is closed.
    `SecurityException` - if the security of the application does not have read access for the directory.
    `IllegalModeException` - if the application does have read access to the connection's target but has opened the connection in `Connector.WRITE` mode.
    `NullPointerException` - if `filter` is `null`.
    `IllegalArgumentException` - if filter contains any path specification or is an invalid filename for the platform (e.g. contains characters invalid for a filename on the platform).

### create

    public void create()
                throws IOException

  Creates a file corresponding to the file string provided in the Connector.open() method for this FileConnection. The file is created immediately on the actual file system upon invocation of this method. Files are created with zero length and data can be put into the file through output streams opened on the file. This method creates non existing directories specified in the file's path.

  Throws:
    `SecurityException` - if the security of the application does not have write access for the file.
    `IllegalModeException` - if the application does have write access to the file but has opened the connection in `Connector.READ` mode.
    `IOException` - if invoked on an existing file is used to create directories), the connection's target has a trailing "/" to denote a directory, the target file system is not accessible, or an unspecified error occurs preventing creation of the file.
    `ConnectionClosedException` - if the connection is closed.

### mkdir

    public void mkdir()
               throws IOException

  Creates a directory corresponding to the directory string provided in the Connector.open() method. The directory is created immediately on the actual file system upon invocation of this method. Directories in the specified path are not recursively created and must be explicitly created before subdirectories can be created.

  Throws:
    `SecurityException` - if the security of the application does not have write access to the directory.
    `IllegalModeException` - if the application does have write access to the directory but has opened the connection in `Connector.READ` mode.
    `IOException` - if invoked on an existing directory or on any file (`create()` is used to create files), the target file sytem is not accessible, or an unspecified error occurs preventing creation of the directory.
    `ConnectionClosedException` - if the connection is closed.

### exists

    public boolean exists()

  Checks if the file or directory specified in the URL passed to the Connector.open() method exists.

  Returns:
    true if the connnection's target exists and is accessible, otherwise false.
  Throws:
    `SecurityException` - if the security of the application does not have read access for the connection's target.
    `IllegalModeException` - if the application does have read access to the connection's target but has opened the connection in `Connector.WRITE` mode.
    `ConnectionClosedException` - if the connection is closed.

### isDirectory

    public boolean isDirectory()

  Checks if the URL passed to the Connector.open() is a directory.

  Returns:
    True if the connection's target exists, is accessible, and is a directory, otherwise false.
  Throws:
    `SecurityException` - if the security of the application does not have read access for the connection's target.
    `ConnectionClosedException` - if the connection is closed.
    `IllegalModeException` - if the application does have read access to the connection's target but has opened the connection in `Connector.WRITE` mode.

### delete

    public void delete()
                throws IOException

  Deletes the file or directory specified in the Connector.open() URL. The file or directory is deleted immediately on the actual file system upon invocation of this method. All open input and output streams are automatically flushed and closed. Attempts to further use those streams result in an `IOException`. The FileConnection instance object remains open and available for use.

  Throws:
    `ConnectionClosedException` - if the connection is closed.
    `SecurityException` - if the security of the application does not have write access to the connection's target.
    `IllegalModeException` - if the application does have write access to the connection's target but has opened the connection in `Connector.READ` mode.
    `IOException` - If the target is a directory and it is not empty, the connection target does not exist or is unaccessible, or an unspecified error occurs preventing deletion of the target.

### rename

    public void rename(String newName)
                throws IOException

  Renames the selected file or directory to a new name in the same directory. The file or directory is renamed immediately on the actual file system upon invocation of this method. No file or directory by the original name exists after this method call. All previously open input and output streams are automatically flushed and closed. Attempts to further use those streams result in an `IOException`. The FileConnection instance object remains open and available for use, referring now to the file or directory by its new name.

  Parameters:
    `newName` - The new name of the file or directory. The name must not contain any path specification; the file or directory remains in its same directory as before this method call.
  Throws:
    `IOException` - if the connection's target does not exist, the connection's target is not accessible, a file or directory already exists by the `newName`, or `newName` is an invalid filename for the platform (e.g. contains characters invalid in a filename on the platform).
    `ConnectionClosedException` - if the connection is closed.
    `SecurityException` - if the security of the application does not have write access to the connection's target.
    `IllegalModeException` - if the application does have write access to the connection's target but has opened the connection in `Connector.READ` mode.
    `NullPointerException` - if `newName` is `null`.
    `IllegalArgumentException` - if `newName` contains any path specification.

### truncate

    public void truncate(long byteOffset)
                  throws IOException

  Truncates the file, discarding all data from the given byte offset to the current end of the file. If the byte offset provided is greater than or equal to the file's current byte count, the method returns without changing the file. Any open streams are flushed automatically before the truncation occurs.

  Parameters:
    `byteOffset` - the offset into the file from which truncation occurs.
  Throws:
    `IOException` - if invoked on a directory or the file does not exist or is not accessible.
    `ConnectionClosedException` - if the connection is closed.
    `SecurityException` - if the security of the application does not have write access to the file.
    `IllegalModeException` - if the application does have write access to the file but has opened the connection in `Connector.READ` mode.
    `IllegalArgumentException` - if `byteOffset` is less than zero.

### setFileConnection

    public void setFileConnection(String fileName)
                           throws IOException

  Resets this FileConnection object to another file or directory. This allows reuse of the FileConnection object for directory traversal. The current FileConnection object must refer to a directory, and the new file or directory must exist within this directory, or may be the string ".." used to indicate the parent directory for the current connection). The FileConnection instance object remains open and available for use, referring now to the newly specified file or directory.

  Parameters:
    `fileName` - name of the file or directory to which this FileConnection is reset. The fileName must be one of the values returned from the `list()` method, or the string ".." to indicate the parent directory of the current connection. The fileName must not contain any additional path specification; i.e. the file or directory must reside within the current directory.
  Throws:
    `NullPointerException` - if `fileName` is `null`.
    `SecurityException` - if the security of the application does not have the security access to the specified file or directory as requested in the Connector.open method invocation that originally opened this FileConnection.
    `IllegalArgumentException` - if `fileName` contains any path specification or does not yet exist.
    `IOException` - if the current FileConnection is opened on a file, the connection's target is not accessible, or `fileName` is an invalid filename for the platform (e.g. contains characters invalid in a filename on the platform).
    `ConnectionClosedException` - if the connection is closed.

### getName

    public String getName()

  Returns the name of a file or directory excluding the URL schema and all paths. Directories are denoted with a trailing slash "/" in their returned name. The String resulting from this method looks as follows:

         <directory>/

  or

         <filename.extension>

  or if no file extension

         <filename>

  Returns:
    The name of a file or directory.

### getPath

    public String getPath()

  Returns the path excluding the file or directory name and the "file" URL schema and host from where the file or directory specified in the Connector.open() method is opened. `getName()` can be appended to this value to get a fully qualified path filename. The String resulting from this method looks as follows:

         /<root>/<directory>/

  Returns:
    The path of a file or directory in the format specified above.

### getURL

    public String getURL()

  Returns the full file URL including the scheme, host, and path from where the file or directory specified in the Connector.open() method is opened. The string returned is in an escaped ASCII format as defined by RFC 2396. The resulting String looks as follows:

         file://<host>/<root>/<directory>/<filename.extension>

  or

         file://<host>/<root>/<directory>/<directoryname>/

  Returns:
    The URL of a file or directory in the format specified above.

### lastModified

    public long lastModified()

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

  Returns:
    A long value representing the time the file was last modified, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970), or 0L if an I/O error occurs. If modification date is not supported by the underlying platform and/or file system, then 0L is also returned. If the connection's target does not exist or is not accessible, 0L is returned.
  Throws:
    `SecurityException` - if the security of the application does not have read access for the connection's target.
    `IllegalModeException` - if the application does have read access to the connection's target but has opened the connection in `Connector.WRITE` mode.
    `ConnectionClosedException` - if the connection is closed.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| IM Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a comment or suggestion Version 2.0 of IM Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright (c) 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.