|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
@TransactionType(value=NOT_SUPPORTED) public interface FileConnection
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 forConnector.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
EveryFileConnection 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 readingopenOutputStream() and openDataOutputStream() throw an
IOException if the connection was not opened for writingExamples
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.
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 |
|---|
boolean canRead()
throws IOException
true if and only if the file specified by the
pathname of this file connection's URL exists and can
be read; false otherwise.
IOException - If this file connection has been closed.
SecurityException - If the protection domain of the caller denies read access to
the file.
boolean canWrite()
throws IOException
true if and only if the file specified by the
pathname of this file connection's URL exists and can
be modified; false otherwise.
IOException - If this file connection has been closed.
SecurityException - If the protection domain of the caller denies write access to
the file.
boolean createNewFile()
throws IOException
true if the named file does not exist and was
successfully created; false if the named file
already exists.
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.
boolean delete()
throws IOException
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.
true if and only if the file or directory is
successfully deleted; false otherwise.
IOException - If this file connection has been closed.
SecurityException - If the protection domain of the caller denies write access
to the file.
boolean deleteAll()
throws IOException
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.
true if and only if the file or directory is
successfully deleted; false otherwise.
IOException - If this file connection has been closed.
SecurityException - If the protection domain of the caller denies write access
to the file.
void deleteOnReset()
throws IOException
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.
IOException - If this file connection has been closed.
boolean exists()
throws IOException
true if and only if the file or directory denoted
by the pathname of this file connection's URL exists;
false otherwise.
IOException - If this file connection has been closed.
SecurityException - If the protection domain of the caller denies read access to
the file or directory.String getURL()
long getFreeSpace()
throws IOException
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.
getTotalSpace().
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.String getName()
String getParent()
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.
null if
this pathname does not name a parent.String getPath()
long getTotalSpace()
throws IOException
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.
boolean isDirectory()
throws IOException
true if and only if the file denoted by the
pathname of this file connection's URL exists and is a
directory; false otherwise.
IOException - If this file connection has been closed.
SecurityException - If the protection domain of the caller denies read access to
the file.
long getLastModified()
throws IOException
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.
IOException - If this file connection has been closed.
SecurityException - If the protection domain of the caller denies read access to
the file.
long getLength()
throws IOException
0L if the file does not
exist.
IOException - If this file connection has been closed.
SecurityException - If the protection domain of the caller denies read access to
the file.
Enumeration<String> list()
throws IOException
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.
null if the pathname of this file connection's URL
does not denote a directory, or if an I/O error occurs.
IOException - If this file connection has been closed.
SecurityException - If the protection domain of the caller denies read access to
the directory.open(String)
boolean mkdir()
throws IOException
true if and only if the directory was created;
false otherwise.
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.
boolean mkdirs()
throws IOException
true if and only if the directory was created,
along with all necessary parent directories; false
otherwise.
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.
boolean renameTo(String destFileURL)
throws IOException
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.
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.
true if and only if the renaming succeeded;
false otherwise.
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
boolean setLastModified(long time)
throws IOException
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
method will return the (possibly truncated) getLastModified()time argument
that was passed to this method.
time - The new last-modified time, measured in milliseconds since the
epoch (00:00:00 GMT, January 1, 1970).
true if and only if the operation succeeded;
false otherwise.
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.
boolean setReadable(boolean readable)
throws IOException
readable - If true, sets the access permission to allow
read operations; if false to disallow read
operations.
true if and only if the operation succeeded;
false otherwise.
IOException - If this file connection has been closed.
SecurityException - If the protection domain of the caller denies write access to
the file.
boolean setReadOnly()
throws IOException
true if and only if the operation succeeded;
false otherwise.
IOException - If this file connection has been closed.
SecurityException - If the protection domain of the caller denies write access to
the named file.
boolean setWritable(boolean writable)
throws IOException
writable - If true, sets the access permission to allow
write operations; if false to disallow write
operations.
true if and only if the operation succeeded;
false otherwise.
IOException - If this file connection has been closed.
SecurityException - If the protection domain of the caller denies write access to
the named file.
FileConnection open(String fileURL)
throws IOException
list() and getParent() methods.
fileURL - a file URL; if relative, it is resolved against the current
file URL.
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.list(),
getParent()
OutputStream openOutputStream()
throws IOException
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.
openOutputStream in interface OutputConnectionIOException - 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.
DataOutputStream openDataOutputStream()
throws IOException
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.
openDataOutputStream in interface OutputConnectionIOException - 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.
OutputStream openOutputStream(boolean append)
throws IOException
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.
append - If true, if true, then bytes will be written to the
end of the file rather than the beginning.
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.
DataOutputStream openDataOutputStream(boolean append)
throws IOException
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.
append - If true, if true, then bytes will be written to the
end of the file rather than the beginning.
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.
InputStream openInputStream()
throws IOException
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.
openInputStream in interface InputConnectionIOException - 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.
DataInputStream openDataInputStream()
throws IOException
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.
openDataInputStream in interface InputConnectionIOException - 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.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||