|
|||||||||
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 OutputConnection
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() 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 OutputConnection
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.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 InputConnection
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.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 InputConnection
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.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |