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:

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.


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