FileConnection (Java Card API, Connected Edition)
Date: 2009-12-11

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

## javacardx.io
Interface FileConnection

All Superinterfaces:
  Connection, InputConnection, OutputConnection, StreamConnection

    @TransactionType(value=NOT_SUPPORTED)
    public interface FileConnection

extends StreamConnection

This interface defines the file stream connection.

A file is accessed using a generic connection string with a `file` scheme, e.g., `file:///transit/pos/log.txt`.

Opening File Connections

BNF Format for `Connector.open()` string

The URI must conform to the BNF syntax specified below. If the URI does not conform to this syntax, an `IllegalArgumentException` is thrown.

<file_connection_string> | ::= "file://"<path>

Opening and Closing Streams

Every `FileConnection` is a `StreamConnection` that provides a `Connection` object as well as an `InputStream` and `OutputStream` to handle the I/O associated with the connection. Each of these interfaces has its own `close()` method. Closing of the input or output stream closes just that side of the connection. E.g., closing the `InputStream` will permit the `OutputStream` to continue writing data.

Every `FileConnection` is a `StreamConnection` that has one underlying `InputStream` and one `OutputStream`. Opening a `DataInputStream` counts as opening an `InputStream` and opening a `DataOutputStream` counts as opening an `OutputStream`. Trying to open another `InputStream` or `OutputStream` causes an `IOException`. Trying to open the `InputStream` or `OutputStream` after they have been closed causes an `IOException`.

The access mode parameter of the `Connector.open()` method only affects the methods that open input streams and output streams:

- `openInputStream()` and `openDataInputStream()` throw an `IOException` if the connection was not opened for reading
- `openOutputStream()` and `openDataOutputStream()` throw an `IOException` if the connection was not opened for writing

The parent directory of the file or directory denoted by the pathname of a file connection's URL is always implicitly open in read/write mode. Some operations on that directory may nevertheless fail depending on the permissions mode set for that directory.

Examples

The following example shows how a `FileConnection` would be used to access a file and append content to the end of that file:

     FileConnection fc = (FileConnection) Connector.open(
             "file:///transit/pos/log.txt", Connector.WRITE);
     OutputStream os = fc.openOutputStream(true);
     os.write("...");
     ...
     os.close();
     fc.close();

The following example shows how a `FileConnection` would be used to walk through a directory to process files with a specific extension:

     FileConnection rootfc = (FileConnection) Connector.open(
             "file:///transit/pos/tmp/", Connector.READ);
     for (String child : rootfc.list()) {
         if (child.endsWith(".txt")) {
             FileConnection childfc = rootfc.open(child);
             if (!childfc.isDirectory()) {
                 // process the file
             }
             childfc.close();
         }
     }
     rootfc.close();

File Systems and Partitions

Instances of this class may or may not denote an actual file-system object such as a file or a directory. If it does denote such an object then that object resides in a partition. A partition is a portion of storage for a file system. A single physical data storage may contain multiple partitions. The object, if any, will reside on the partition named by some ancestor of the absolute form of the file connection's pathname.

File Permissions Mode

A file system implements restrictions to read and write operations on the actual file-system objects. These restrictions are known as access permissions. A file system object has a single set of access permission attributes that applies to any application attempting to perform read or write operations. This set of access permission attributes is also known as the file's permissions mode.

Note that file system access permissions are different from, yet complementary to, the permissions of protection domains. Protection domain permissions that apply to file connections are `ConnectorPermission` objects with `file` URL target names.

File-system access permissions on a file-system object (its permissions mode) may cause some methods in this class to fail either gracefully with an appropriate return value or with an `IOException`, while protection domain permissions may cause some methods to fail with a `SecurityException`.

Simplified Stream Methods on Connector

Please note the following: The `Connector` class defines the convenience methods `openXXXStream(String url)` for retrieving an input or output stream directly for a specified URL. Please be aware that using these methods implies certain restrictions. You will not get a reference to the actual file connection, but rather just references to the input or output stream of the file connection. Not having a reference to the file connection means that you will not be able to perform certain operations defined by this interface on the file resource, such as getting the file's length, deleting the file...

See Runtime Environment Specification for the Java Card Platform, Connected Edition, chapter 9 for details regarding file system support.

Since:
  Java Card 3.0
See Also:
  `ConnectorPermission`

Method Summary
`boolean` | `canRead()` Tests whether the file denoted by the pathname of this file connection's URL can be read.
`boolean` | `canWrite()` Tests whether the file denoted by the pathname of this file connection's URL can be modified.
`boolean` | `createNewFile()` Atomically creates a new, empty file named by the pathname of this file connection's URL if and only if a file with that name does not yet exist.
`boolean` | `delete()` Deletes the file or directory denoted by the pathname of this file connection's URL.
`boolean` | `deleteAll()` Deletes the file or directory denoted by the pathname of this file connection's URL.
`void` | `deleteOnReset()` Requests that the file or directory denoted by the pathname of this file connection's URL be deleted when the platform is reset.
`boolean` | `exists()` Tests whether the file or directory denoted by the pathname of this file connection's URL exists.
`long` | `getFreeSpace()` Returns the number of unallocated bytes in the partition named by the pathname of this file connection's URL.
`long` | `getLastModified()` Returns the time that the file denoted by the pathname of this file connection's URL was last modified.
`long` | `getLength()` Returns the length of the file denoted by the pathname of this file connection's URL.
`String` | `getName()` Returns the name of the file or directory denoted by the pathname of this file connection's URL.
`String` | `getParent()` Returns the canonical pathname of the parent directory of the file or directory denoted by the pathname of this file connection's URL.
`String` | `getPath()` Returns the canonical pathname of this file connection's URL.
`long` | `getTotalSpace()` Returns the size of the partition named by the pathname of this file connection's URL.
`String` | `getURL()` Gets the canonical file URL associated to this file connection.
`boolean` | `isDirectory()` Tests whether the file denoted by the pathname of this file connection's URL is a directory.
`Enumeration<String>` | `list()` Returns an enumeration of strings naming the files and directories in the directory denoted by the pathname of this file connection's URL.
`boolean` | `mkdir()` Creates the directory named by the pathname of this file connection's URL.
`boolean` | `mkdirs()` Creates the directory named by the pathname of this file connection's URL, including any necessary but nonexistent parent directories.
`FileConnection` | `open(String fileURL)` Opens a file connection to the provided - possibly relative - file URL.
`DataInputStream` | `openDataInputStream()` Opens and returns a data input stream for this file connection.
`DataOutputStream` | `openDataOutputStream()` Opens and returns a data output stream for this file connection.
`DataOutputStream` | `openDataOutputStream(boolean append)` Opens and returns a data output stream for this file connection.
`InputStream` | `openInputStream()` Opens and returns an input stream for this file connection.
`OutputStream` | `openOutputStream()` Opens and returns an output stream for this file connection.
`OutputStream` | `openOutputStream(boolean append)` Opens and returns an output stream for this file connection.
`boolean` | `renameTo(String destFileURL)` Renames the file denoted by the pathname of this file connection's URL.
`boolean` | `setLastModified(long time)` Sets the last-modified time of the file or directory denoted by the pathname of this file connection's URL.
`boolean` | `setReadable(boolean readable)` Sets the read permission for the file denoted by the pathname of this file connection's URL.
`boolean` | `setReadOnly()` Marks the file or directory denoted by the pathname of this file connection's URL so that only read operations are allowed.
`boolean` | `setWritable(boolean writable)` Sets the write permission for the file denoted by the pathname of this file connection's URL.

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

Method Detail

### canRead

    boolean canRead()
                    throws IOException

  Tests whether the file denoted by the pathname of this file connection's URL can be read.

  Returns:
    `true` if and only if the file specified by the pathname of this file connection's URL exists and can be read; `false` otherwise.
  Throws:
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller denies read access to the file.

### canWrite

    boolean canWrite()
                     throws IOException

  Tests whether the file denoted by the pathname of this file connection's URL can be modified.

  Returns:
    `true` if and only if the file specified by the pathname of this file connection's URL exists and can be modified; `false` otherwise.
  Throws:
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller denies write access to the file.

### createNewFile

    boolean createNewFile()
                          throws IOException

  Atomically creates a new, empty file named by the pathname of this file connection's URL if and only if a file with that name does not yet exist. The check for the existence of the file and the creation of the file if it does not exist are a single operation that is atomic with respect to all other filesystem activities that might affect the file.

  Returns:
    `true` if the named file does not exist and was successfully created; `false` if the named file already exists.
  Throws:
    `IOException` - If this file connection has been closed or some other kind of I/O error occurs. *
    `SecurityException` - If the protection domain of the caller denies write access to the file.

### delete

    boolean delete()
                   throws IOException

  Deletes the file or directory denoted by the pathname of this file connection's URL. If that pathname denotes a directory, then the directory must be empty in order to be deleted.

  Any input or output stream opened through this connection is first flushed and closed.

  This operation must fail if the file or directory is currently open.

  Returns:
    `true` if and only if the file or directory is successfully deleted; `false` otherwise.
  Throws:
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller denies write access to the file.

### deleteAll

    boolean deleteAll()
                      throws IOException

  Deletes the file or directory denoted by the pathname of this file connection's URL. If that pathname denotes a directory, then all the directory's content is deleted recursively.

  Any input or output stream opened through this connection is first flushed and closed.

  This operation must fail if the file or directory or any of the contained files or directories is currently open.

  Returns:
    `true` if and only if the file or directory is successfully deleted; `false` otherwise.
  Throws:
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller denies write access to the file.

### deleteOnReset

    void deleteOnReset()
                       throws IOException

  Requests that the file or directory denoted by the pathname of this file connection's URL be deleted when the platform is reset. If that pathname denotes a directory, then all the directory's content is deleted recursively.

  This method only applies to a file or directory that does not exist yet and will be created by this file connection. Calling this method for a file or directory that already exists has no effect.

  Once deletion has been requested, it is not possible to cancel the request. This method should therefore be used with care.

  Throws:
    `IOException` - If this file connection has been closed.

### exists

    boolean exists()
                   throws IOException

  Tests whether the file or directory denoted by the pathname of this file connection's URL exists.

  Returns:
    `true` if and only if the file or directory denoted by the pathname of this file connection's URL exists; `false` otherwise.
  Throws:
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller denies read access to the file or directory.

### getURL

    String getURL()

  Gets the canonical file URL associated to this file connection.

  Returns:
    the canonical file URL associated to this file connection.

### getFreeSpace

    long getFreeSpace()
                      throws IOException

  Returns the number of unallocated bytes in the partition named by the pathname of this file connection's URL.

  The returned number of unallocated bytes is a hint, but not a guarantee, that it is possible to use most or any of these bytes. The number of unallocated bytes is most likely to be accurate immediately after this call. This method makes no guarantee that write operations to this file system will succeed.

  Returns:
    The number of unallocated bytes on the partition `0L` if the abstract pathname does not name a partition. This value will be less than or equal to the total file system size returned by `getTotalSpace()`.
  Throws:
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller denies read access to the file named by the pathname of this file connection's URL.

### getName

    String getName()

  Returns the name of the file or directory denoted by the pathname of this file connection's URL. This is just the last name in the pathname's name sequence. If the pathname's name sequence is empty, then the empty string is returned.

  Returns:
    The name of the file or directory denoted by the pathname of this file connection's URL, or the empty string if that pathname's name sequence is empty.

### getParent

    String getParent()

  Returns the canonical pathname of the parent directory of the file or directory denoted by the pathname of this file connection's URL. Returns the pathname string of the pathname's parent, or `null` if the pathname of this file connection's URL does not name a parent directory.

  The parent of a pathname consists of each name in the pathname's name sequence except for the last. If the name sequence is empty then the pathname does not name a parent directory.

  Returns:
    The canonical pathname of the parent directory named by the pathname of this file connection's URL, or `null` if this pathname does not name a parent.

### getPath

    String getPath()

  Returns the canonical pathname of this file connection's URL.

  Returns:
    The canonical pathname of this file connection's URL.

### getTotalSpace

    long getTotalSpace()
                       throws IOException

  Returns the size of the partition named by the pathname of this file connection's URL.

  Returns:
    The size, in bytes, of the partition or `0L` if the pathname of this file connection's URL does not name a partition.
  Throws:
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller denies read access to the file named by the pathname of this file connection's URL.

### isDirectory

    boolean isDirectory()
                        throws IOException

  Tests whether the file denoted by the pathname of this file connection's URL is a directory.

  Returns:
    `true` if and only if the file denoted by the pathname of this file connection's URL exists and is a directory; `false` otherwise.
  Throws:
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller denies read access to the file.

### getLastModified

    long getLastModified()
                         throws IOException

  Returns the time that the file denoted by the pathname of this file connection's URL 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 the file does not exist or if an I/O error occurs.
  Throws:
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller denies read access to the file.

### getLength

    long getLength()
                   throws IOException

  Returns the length of the file denoted by the pathname of this file connection's URL. The return value is unspecified if this pathname denotes a directory.

  Returns:
    The length, in bytes, of the file denoted by the pathname of this file connection's URL, or `0L` if the file does not exist.
  Throws:
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller denies read access to the file.

### list

    Enumeration<String> list()
                             throws IOException

  Returns an enumeration of strings naming the files and directories in the directory denoted by the pathname of this file connection's URL.

  If the pathname of this file connection's URL does not denote a directory, then this method returns `null`. Otherwise an enumeration of strings is returned, one for each file or directory in the directory. Names denoting the directory itself and the directory's parent directory are not included in the result. Each string is a file name rather than a complete path.

  There is no guarantee that the name strings in the resulting array will appear in any specific order; they are not, in particular, guaranteed to appear in alphabetical order.

  Returns:
    An enumeration of strings naming the files and directories in the directory denoted by the pathname of this file connection's URL. The enumeration will be empty if the directory is empty. Returns `null` if the pathname of this file connection's URL does not denote a directory, or if an I/O error occurs.
  Throws:
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller denies read access to the directory.
  See Also:
    `open(String)`

### mkdir

    boolean mkdir()
                  throws IOException

  Creates the directory named by the pathname of this file connection's URL.

  Returns:
    `true` if and only if the directory was created; `false` otherwise.
  Throws:
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller does not permit the named directory to be created.

### mkdirs

    boolean mkdirs()
                   throws IOException

  Creates the directory named by the pathname of this file connection's URL, including any necessary but nonexistent parent directories. Note that if this operation fails it may have succeeded in creating some of the necessary parent directories.

  Returns:
    `true` if and only if the directory was created, along with all necessary parent directories; `false` otherwise.
  Throws:
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller does not permit the named directory and all necessary parent directories to be created.

### renameTo

    boolean renameTo(String destFileURL)
                     throws IOException

  Renames the file denoted by the pathname of this file connection's URL.

  The rename operation might not be able to move a file from one filesystem to another, it might not be atomic, and it might not succeed if a file with the destination pathname already exists. The return value should always be checked to make sure that the rename operation was successful.

  Parameters:
    `destFileURL` - The new pathname for the file denoted by the pathname of this file connection's URL. `destFileURL` may be a relative or absolute pathname - that is a relative URL - or may be an absolute file URL. If relative, `destFileURL` will be resolved against the current application's root file URI.
  Returns:
    `true` if and only if the renaming succeeded; `false` otherwise.
  Throws:
    `IllegalArgumentException` - If `destFileURL` is not a well-formed file URL.
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller denies write access to either the old or new pathnames or if `destFileURL` is not in the current application's file namespace.
    `NullPointerException` - If parameter `destFileURL` is `null`

### setLastModified

    boolean setLastModified(long time)
                            throws IOException

  Sets the last-modified time of the file or directory denoted by the pathname of this file connection's URL.

  The argument may be truncated to fit the supported precision. If the operation succeeds and no intervening operations on the file take place, then the next invocation of the ``getLastModified()`` method will return the (possibly truncated) `time` argument that was passed to this method.

  Parameters:
    `time` - The new last-modified time, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
  Returns:
    `true` if and only if the operation succeeded; `false` otherwise.
  Throws:
    `IllegalArgumentException` - If the argument is negative.
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller denies write access to the named file.

### setReadable

    boolean setReadable(boolean readable)
                        throws IOException

  Sets the read permission for the file denoted by the pathname of this file connection's URL.

  Parameters:
    `readable` - If `true`, sets the access permission to allow read operations; if `false` to disallow read operations.
  Returns:
    `true` if and only if the operation succeeded; `false` otherwise.
  Throws:
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller denies write access to the file.

### setReadOnly

    boolean setReadOnly()
                        throws IOException

  Marks the file or directory denoted by the pathname of this file connection's URL so that only read operations are allowed. After invoking this method the file or directory is guaranteed not to change until it is either deleted or marked to allow write access.

  Returns:
    `true` if and only if the operation succeeded; `false` otherwise.
  Throws:
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller denies write access to the named file.

### setWritable

    boolean setWritable(boolean writable)
                        throws IOException

  Sets the write permission for the file denoted by the pathname of this file connection's URL.

  Parameters:
    `writable` - If `true`, sets the access permission to allow write operations; if `false` to disallow write operations.
  Returns:
    `true` if and only if the operation succeeded; `false` otherwise.
  Throws:
    `IOException` - If this file connection has been closed.
    `SecurityException` - If the protection domain of the caller denies write access to the named file.

### open

    FileConnection open(String fileURL)
                        throws IOException

  Opens a file connection to the provided - possibly relative - file URL. If the provided file URL is relative, it will be resolved against the current file URL. This method can directly be used with the result of the `list()` and `getParent()` methods.

  Parameters:
    `fileURL` - a file URL; if relative, it is resolved against the current file URL.
  Returns:
    A new FileConnection object.
  Throws:
    `IllegalArgumentException` - If `fileURL` is not a well-formed file URL.
    `NullPointerException` - If `fileURL` is `null`.
    `ConnectionNotFoundException` - if it can be immediately determined that the target of the name cannot be found.
    `IOException` - If this file connection has been closed or some other kind of I/O error occurs.
    `SecurityException` - If `fileURL` is not in the application's file namespace.
  See Also:
    `list()`, `getParent()`

### openOutputStream

    OutputStream openOutputStream()
                                  throws IOException

  Opens and returns an output stream for this file connection.

  If the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for writing for any other reason then an IOException is thrown.

  Specified by:
    `openOutputStream` in interface `OutputConnection`
  Returns:
    An output stream
  Throws:
    `IOException` - If this file connection has been closed or if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason
    `SecurityException` - If the protection domain of the caller denies write access to the named file.

### openDataOutputStream

    DataOutputStream openDataOutputStream()
                                          throws IOException

  Opens and returns a data output stream for this file connection.

  If the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for writing for any other reason then an IOException is thrown.

  Specified by:
    `openDataOutputStream` in interface `OutputConnection`
  Returns:
    An output stream
  Throws:
    `IOException` - If this file connection has been closed or if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason
    `SecurityException` - If the protection domain of the caller denies write access to the named file.

### openOutputStream

    OutputStream openOutputStream(boolean append)
                                  throws IOException

  Opens and returns an output stream for this file connection.

  If the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for writing for any other reason then an IOException is thrown.

  If the `append` parameter is true, then bytes will be written to the end of the file rather than the beginning.

  Parameters:
    `append` - If `true`, if true, then bytes will be written to the end of the file rather than the beginning.
  Returns:
    An output stream
  Throws:
    `IOException` - If this file connection has been closed or if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason
    `SecurityException` - If the protection domain of the caller denies write access to the named file.

### openDataOutputStream

    DataOutputStream openDataOutputStream(boolean append)
                                          throws IOException

  Opens and returns a data output stream for this file connection.

  If the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for writing for any other reason then an IOException is thrown.

  If the `append` parameter is true, then bytes will be written to the end of the file rather than the beginning.

  Parameters:
    `append` - If `true`, if true, then bytes will be written to the end of the file rather than the beginning.
  Returns:
    An output stream
  Throws:
    `IOException` - If this file connection has been closed or if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason
    `SecurityException` - If the protection domain of the caller denies write access to the named file.

### openInputStream

    InputStream openInputStream()
                                throws IOException

  Opens and returns an input stream for this file connection.

  If the file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading then an IOException is thrown.

  Specified by:
    `openInputStream` in interface `InputConnection`
  Returns:
    An input stream
  Throws:
    `IOException` - If this file connection has been closed or if the file does not exist, is a directory rather than a regular file, or cannot be opened for any other reason.
    `SecurityException` - If the protection domain of the caller denies read access to the named file.

### openDataInputStream

    DataInputStream openDataInputStream()
                                        throws IOException

  Opens and returns a data input stream for this file connection.

  If the file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading then an IOException is thrown.

  Specified by:
    `openDataInputStream` in interface `InputConnection`
  Returns:
    An input stream
  Throws:
    `IOException` - If this file connection has been closed or if the file does not exist, is a directory rather than a regular file, or cannot be opened for any other reason.
    `SecurityException` - If the protection domain of the caller denies read access to the named file.

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

Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.