|
IM Profile | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
This interface is intended to access files or directories that are located on removeable media and/or file systems on a device.
Device internal filesystems in memory may also be accessed through
this class as well, provided there is underlying hardware and OS support.
If file connections are not supported to a particular media or file system,
attempts to open a file connection to the media or file system through
Connector.open()
results in an
javax.microedition.io.IOException
being thrown.
The format of the input string used to access a FileConnection through
Connector.open()
must follow the format of a fully-qualified,
absolute path file name as described by the file
URL format in IETF RFCs 1738 & 2396. Further detail for the File
URL format can be found in the com.siemens.mp.microedition.io.file package description.
A single connection object only references a single file or
directory at a time. In some cases, a connection object can be reused to
refer to a different file or directory than it was originally associated with
(see setFileConnection(java.lang.String)
). In general, the best approach to reference
a different file or directory is by establishing a completely separate
connection through the Connector.open()
method.
File connection is different from other Generic Connection Framework
connections in that a connection object can be successfully returned from
the Connector.open()
method without actually referencing an
existing entity (in this case, a file or directory). This behavior
allows the creation of new files and directories on a file system.
For example, the following code can be used to create
a new file on a file system, where CFCard is a valid existing file
system root name for a given implementation:
try {
FileConnection fconn = (FileConnection)Connector.open("file:///CFCard/newfile.txt");
// If no exception is thrown, then the URI is valid, but the file may or may not exist.
if (!fconn.exists())
fconn.create(); // create the file if it doesn't exist
fconn.close();
}
catch (IOException ioe) {
}
Developers should always check for the file's or directory's existence
after a connection is established to determine if the file or directory
actually exists. Similarly, files or directories can be deleted using the
delete()
method, and developers should close the connection
immediately after deletion to prevent exceptions from accessing a connection
to a non-existent file or directory.
A file connection's open status is unaffected by the opening and closing of
input and output streams from the file connection; the file connection stays
open until close()
is invoked on the FileConnection instance.
Input and output streams may be opened and closed multiple times on a
FileConnection instance.
All FileConnection
instances have one underlying
InputStream
and one OutputStream
. Opening a
DataInputStream
counts as opening an InputStream,
and opening a DataOutputStream
counts as opening an
OutputStream
. A FileConnection
instance can have
only one InputStream
and one OutputStream
open at
any one time. Trying to open more than one InputStream
or more
than one OutputStream
from a StreamConnection
causes an IOException
. Trying to open an InputStream
or an OutputStream
after the FileConnection
has
been closed causes an IOException
.
The skip methode of the InputStream
on a FileConnection
does not skip
the bytes from the current position. It skips the bytes from the begin
of the stream.
The inherited StreamConnection
methods in a
FileConnection
instance are not synchronized. The only stream
method that can be called safely from another thread is close
.
When close
is invoked on a stream that is executing in another
thread, any pending I/O method MUST throw an
InterruptedIOException
. In the above case, implementations
SHOULD try to throw the exception in a timely manner. When all open streams
have been closed, and when the FileConnection
is closed, any
pending I/O operations MUST be interrupted in a timely manner.
Data written to the output streams of these FileConnection
objects is not guaranteed to be flushed to the stream's destination
(and subsequently made available to any input streams) until either
flush()
or close()
is invoked on the stream.
Access to file connections is restricted to prevent unauthorized manipulation
of data. The access security model applied to the file connection
is defined by the implementing profile. The security model is applied on
the invocation of the Connector.open()
method with a valid file
connection string. The mode provided in the open()
method
(Connector.READ_WRITE
by default) indicates the application's
request for access rights for the indicated file or directory and is
therefore checked against the security scheme. All three connections modes
(READ_WRITE, WRITE_ONLY,
and READ_ONLY
) are
supported for a file connection and determine the access requested from the
security model.
The security model is also applied during use of the returned
FileConnection, specifically when the methods
openInputStream()
, openDataInputStream()
,
openOutputStream()
, and openDataOutputStream()
are
invoked. These methods have implied request for access rights (i.e.
input stream access is requesting read access, and output stream access is
requesting write access). Should the application not be granted the
appropriate read or write access to the file or file system by the profile
authorization scheme, a java.lang.SecurityException
is thrown.
File access through the File Connection API may be restricted to files that
are within a public context and not deemed private or sensitive. This
restriction is intended to protect the device's and other users' files and
data from both malicious and unintentional access. RMS databases cannot be
accessed using the File Connection API. Access to files and directories that
are private to another application, files and directories that are private to
a different user than the current user, system configuration files, and
device and OS specific files and directories may be restricted. In these
situations, a java.lang.SecurityException
is thrown from the
Connector.open()
method if the file, file system, or directory
is not allowed to be accessed.
Permissions are the MIDP 2.0 mechanism by which a MIDlet may request security
access to protected APIs or functions. A MIDlet can request access by including the
permissions in the MIDlet-Permissions
and MIDlet-Permissions-Opt
attributes in its JAD or manifest. Table 1 defines the permissions
applicable to the FileConnection APIs, and the API methods that are protected by
those permissions:
Table 1: FileConnection Permissions and Protected Methods
Permission | Protected API Calls |
---|---|
javax.microedition.io.Connector.file.read |
com.siemens.mp.microedition.io.Connector methods: open("file://...")
|
javax.microedition.io.Connector.file.write |
com.siemens.mp.microedition.io.Connector methods: open("file://...")
|
Note that the following protected API calls from the Table 1 require both read
and write
permissions:
Connector.open("file://...")
if the FileConnection instance is opened in READ_WRITE
Connector.open("file://...", Connector.READ_WRITE)
FileConnection.setFileConnection("file://...")
It should be noted that the permissions protect API calls, regardless of the
data that is being accessed. For example, a successful grant of READ_WRITE
access to the Connector.open("file://...")
method
allows the application to read/write any file or directory, not just the
file/directory used as the method's parameter. The parameters of the API
calls (which indicate the data being accessed) is not a factor at all in
the granting of the permissions, as dictated by MIDP 2.0 security
definitions. For this reason, it is recommended that a user
interaction mode of "one-shot" be used when user authorization is
required so that the user is notified on every instance that a file or directory
is accessed.
FileSystemRegistry
Method Summary | |
long |
availableSize()
Determines the free memory that is available on the file system the file or directory resides on. |
boolean |
canRead()
Checks if the file or directory is readable. |
boolean |
canWrite()
Checks if the file or directory is writable. |
void |
create()
Creates a file corresponding to the file string provided in the Connector.open() method for this FileConnection. |
void |
delete()
Deletes the file or directory specified in the Connector.open() URL. |
long |
directorySize(boolean includeSubDirs)
Determines the size in bytes on a file system of all of the files that are contained in a directory. |
boolean |
exists()
Checks if the file or directory specified in the URL passed to the Connector.open() method exists. |
long |
fileSize()
Determines the size of a file on the file system. |
String |
getName()
Returns the name of a file or directory excluding the URL schema and all paths. |
String |
getPath()
Returns the path excluding the file or directory name and the "file" URL schema and host from where the file or directory specified in the Connector.open() method is opened. |
String |
getURL()
Returns the full file URL including the scheme, host, and path from where the file or directory specified in the Connector.open() method is opened. |
boolean |
isDirectory()
Checks if the URL passed to the Connector.open() is a directory. |
boolean |
isHidden()
Checks if the file is hidden. |
boolean |
isOpen()
Returns an indication of whether the file connection is currently open or not. |
long |
lastModified()
Returns the time that the file denoted by the URL specified in the Connector.open() method was last modified. |
Enumeration |
list()
Gets a list of all files and directories contained in a directory. |
Enumeration |
list(String filter,
boolean includeHidden)
Gets a filtered list of files and directories contained in a directory. |
void |
mkdir()
Creates a directory corresponding to the directory string provided in the Connector.open() method. |
DataInputStream |
openDataInputStream()
Open and return a data input stream for a connection. |
DataOutputStream |
openDataOutputStream()
Open and return a data output stream for a connection. |
InputStream |
openInputStream()
Open and return an input stream for a connection. |
OutputStream |
openOutputStream()
Open and return an output stream for a connection. |
OutputStream |
openOutputStream(long byteOffset)
This method opens an output stream and positions it at the indicated byte offset in the file. |
void |
rename(String newName)
Renames the selected file or directory to a new name in the same directory. |
void |
setFileConnection(String fileName)
Resets this FileConnection object to another file or directory. |
void |
setHidden(boolean hidden)
Sets the hidden attribute of the selected file to the value provided. |
void |
setReadable(boolean readable)
Sets the file or directory readable attribute to the indicated value. |
void |
setWritable(boolean writable)
Sets the selected file or directory writable attribute to the indicated value. |
long |
totalSize()
Determines the total size of the file system the connection's target resides on. |
void |
truncate(long byteOffset)
Truncates the file, discarding all data from the given byte offset to the current end of the file. |
long |
usedSize()
Determines the used memory of a file system the connection's target resides on. |
Methods inherited from interface javax.microedition.io.Connection |
close |
Method Detail |
public boolean isOpen()
public InputStream openInputStream() throws IOException
openInputStream
in interface InputConnection
IOException
- if an I/O error occurs, if the method is invoked on
a directory, if the connection's target does not
yet exist, or the connection's target is not accessible.
IllegalModeException
- if the application does have read access
to the connection's target but has opened the connection in
Connector.WRITE
mode.
SecurityException
- If the application is not granted read
access to the connection's target.public DataInputStream openDataInputStream() throws IOException
openDataInputStream
in interface InputConnection
IOException
- If an I/O error occurs, if the method is invoked on
a directory, if the connection's target does not
yet exist, or the connection's target is not accessible.
IllegalModeException
- if the application does have read access
to the connection's target but has opened the connection in
Connector.WRITE
mode.
SecurityException
- If the application is not granted read
access to the connection's target.public OutputStream openOutputStream() throws IOException
openOutputStream(long)
should be used to position an output
stream to a different position in the file.
Changes made to a file through an output stream may not be immediately
made to the actual file residing on the file system because
platform and implementation specific use of caching and buffering of the
data. Steam contents and file length extensions are not necessarily
visible outside of the application immediately unless
flush()
is called on the stream. The returned output stream
is automatically and synchronously flushed when it is closed.
openOutputStream
in interface OutputConnection
IOException
- If an I/O error occurs, if the method is invoked on
a directory, the file does not yet exist, or the connection's
target is not accessible.
IllegalModeException
- if the application does have write access
to the connection's target but has opened the connection in
Connector.READ
mode.
SecurityException
- If the application is not granted write
access to the connection's target.openOutputStream(long)
public DataOutputStream openDataOutputStream() throws IOException
openOutputStream(long)
should be used to position an output
stream to a different position in the file.
Changes made to a file through an output stream may not be immediately
made to the actual file residing on the file system because
platform and implementation specific use of caching and buffering of the
data. Steam contents and file length extensions are not necessarily
visible outside of the application immediately unless
flush()
is called on the stream. The returned output stream
is automatically and synchronously flushed when it is closed.
openDataOutputStream
in interface OutputConnection
IOException
- If an I/O error occurs, if the method is invoked on
a directory, the file does not yet exist, or the connection's
target is not accessible.
IllegalModeException
- if the application does have write access
to the connection's target but has opened the connection in
Connector.READ
mode.
SecurityException
- If the application is not granted write
access to the connection's target.openOutputStream(long)
public OutputStream openOutputStream(long byteOffset) throws IOException
Changes made to a file through an output stream may not be immediately
made to the actual file residing on the file system because
platform and implementation specific use of caching and buffering of the
data. Steam contents and file length extensions are not necessarily
visible outside of the application immediately unless
flush()
is called on the stream. The returned output
stream is automatically and synchronously flushed when it is closed.
byteOffset
- number of bytes to skip over from the beginning of
the file when positioning the start of the OutputStream. If
the provided offset is larger than or equal to the current file
size, the OutputStream is positioned at the current end of the
file for appending.
IOException
- If an I/O error occurs, if the method is invoked
on a directory, the file does not yet exist, or the
connection's target is not accessible.
IllegalModeException
- if the application does have write access
to the connection's target but has opened the connection in
Connector.READ
mode.
SecurityException
- if the security if the application does not
allow write access to the file.
IllegalArgumentException
- if byteOffset has a negative value.public long totalSize()
SecurityException
- if the security of the application does not
have read access to the root volume.
IllegalModeException
- if the application does have read access
to the connection's target but has opened the connection in
Connector.WRITE
mode.
ConnectionClosedException
- if the connection is closed.public long availableSize()
SecurityException
- if the security of the application does not
have read access to the root volume.
IllegalModeException
- if the application does have read access
to the directory but has opened the connection in
Connector.WRITE
mode.
ConnectionClosedException
- if the connection is closed.public long usedSize()
SecurityException
- if the security of the application does not
have read access to the root volume.
IllegalModeException
- if the application does have read access
to the directory but has opened the connection in
Connector.WRITE
mode.
ConnectionClosedException
- if the connection is closed.public long directorySize(boolean includeSubDirs) throws IOException
includeSubDirs
- If set to true, the method determines
the size of the given directory and all subdirs
recursively. If false, the method returns the size
of the files in the directory only.
IOException
- if the method is invoked on a file.
SecurityException
- if the security of the application does not
have read access for the directory.
IllegalModeException
- if the application does have read access
to the directory but has opened the connection in
Connector.WRITE
mode.
ConnectionClosedException
- if the connection is closed.public long fileSize() throws IOException
fileSize()
always returns size of the file on the file system,
and not in any pending output stream. flush()
should be used
before calling fileSize()
to ensure the contents
of the output streams opened to the file get written to the file system.
IOException
- if the method is invoked on a directory.
SecurityException
- if the security of the application does not
have read access for the file.
IllegalModeException
- if the application does have read access
to the file but has opened the connection in
Connector.WRITE
mode.
ConnectionClosedException
- if the connection is closed.public boolean canRead()
SecurityException
- if the security of the application does not
have read access for the connection's target.
IllegalModeException
- if the application does have read access
to the connection's target but has opened the connection in
Connector.WRITE
mode.
ConnectionClosedException
- if the connection is closed.setReadable(boolean)
public boolean canWrite()
SecurityException
- if the security of the application does not
have read access for the connection's target.
IllegalModeException
- if the application does have read access
to the connection's target but has opened the connection in
Connector.WRITE
mode.
ConnectionClosedException
- if the connection is closed.setWritable(boolean)
public boolean isHidden()
ConnectionClosedException
- if the connection is closed.
SecurityException
- if the security of the application does not
have read access for the connection's target.
IllegalModeException
- if the application does have read access
to the connection's target but has opened the connection in
Connector.WRITE
mode.setHidden(boolean)
public void setReadable(boolean readable) throws IOException
canRead()
always returns true.
readable
- The new state of the readable flag of the selected file.
IOException
- of the connection's target does not exist or is not
accessible.
ConnectionClosedException
- if the connection is closed.
SecurityException
- if the security of the application does not
have write access to the connection's target.
IllegalModeException
- if the application does have write access
to the connection's target but has opened the connection in
Connector.READ
mode.canRead()
public void setWritable(boolean writable) throws IOException
canWrite()
always returns true.
writable
- The new state of the writable flag of the selected file.
IOException
- if the connection's target does not exist or is not
accessible.
ConnectionClosedException
- if the connection is closed.
SecurityException
- if the security of the application does not
have write access to the connection's target.
IllegalModeException
- if the application does have write access
to the connection's target but has opened the connection in
Connector.READ
mode.canWrite()
public void setHidden(boolean hidden) throws IOException
isHidden()
always
returns false. Since the exact definition of hidden is system-dependent,
this method only works on file systems that support a settable file
attribute. For example, on Win32 and FAT file systems, a file may be
considered hidden if it has been marked as such in the file's
attributes; therefore this method is applicable. However on UNIX
systems a file may be considered to be hidden if its name begins with a
period character ('.'). In the UNIX case, this method may be ignored and
the method to make a file hidden may be the rename()
method.
hidden
- The new state of the hidden flag of the selected file.
IOException
- if the connection's target does not exist or is not
accessible.
ConnectionClosedException
- if the connection is closed.
SecurityException
- if the security of the application does not
have write access to the connection's target.
IllegalModeException
- if the application does have write access
to the connection's target but has opened the connection in
Connector.READ
mode.isHidden()
public Enumeration list() throws IOException
Connector.open()
.
getPath()
). Directories are denoted with a
trailing slash "/" in their returned name. The Enumeration has
zero length if the directory is empty. Any
hidden files and directories in the directory are not included
in the returned list. Any current directory indication (".")
and any parent directory indication ("..") is not included
in the list of files and directories returned.
IOException
- if invoked on a file, the directory does not exist,
the directory is not accessible, or an I/O error occurs.
ConnectionClosedException
- if the connection is closed.
SecurityException
- if the security of the application does not
have read access for the directory.
IllegalModeException
- if the application does have read access
to the directory but has opened the connection in
Connector.WRITE
mode.public Enumeration list(String filter, boolean includeHidden) throws IOException
Connector.open()
.
filter
- String against which all files and directories are
matched for retrieval. An asterisk ("*") can be used as a
wildcard to represent 0 or more occurrences of any character.includeHidden
- boolean indicating whether files marked as hidden
should be included or not in the list of files and directories
returned.
IOException
- if invoked on a file, the directory does not exist,
the directory is not accessible, or an I/O error occurs.
ConnectionClosedException
- if the connection is closed.
SecurityException
- if the security of the application does not
have read access for the directory.
IllegalModeException
- if the application does have read access
to the connection's target but has opened the connection in
Connector.WRITE
mode.
NullPointerException
- if filter
is
null
.
IllegalArgumentException
- if filter contains any path
specification or is an invalid filename for the platform
(e.g. contains characters invalid for a filename on the platform).public void create() throws IOException
SecurityException
- if the security of the application does not
have write access for the file.
IllegalModeException
- if the application does have write access
to the file but has opened the connection in
Connector.READ
mode.
IOException
- if invoked on an existing file is used to
create directories), the connection's target has a
trailing "/" to denote a directory, the target file system
is not accessible, or an unspecified error occurs preventing
creation of the file.
ConnectionClosedException
- if the connection is closed.public void mkdir() throws IOException
SecurityException
- if the security of the application does not
have write access to the directory.
IllegalModeException
- if the application does have write access
to the directory but has opened the connection in
Connector.READ
mode.
IOException
- if invoked on an existing directory or on any file
(create()
is used to create files), the target
file sytem is not accessible, or an unspecified error occurs
preventing creation of the directory.
ConnectionClosedException
- if the connection is closed.public boolean exists()
SecurityException
- if the security of the application does not
have read access for the connection's target.
IllegalModeException
- if the application does have read access
to the connection's target but has opened the connection in
Connector.WRITE
mode.
ConnectionClosedException
- if the connection is closed.public boolean isDirectory()
SecurityException
- if the security of the application does not
have read access for the connection's target.
ConnectionClosedException
- if the connection is closed.
IllegalModeException
- if the application does have read access
to the connection's target but has opened the connection in
Connector.WRITE
mode.public void delete() throws IOException
IOException
. The
FileConnection instance object remains open and available for use.
ConnectionClosedException
- if the connection is closed.
SecurityException
- if the security of the application does not
have write access to the connection's target.
IllegalModeException
- if the application does have write access
to the connection's target but has opened the connection in
Connector.READ
mode.
IOException
- If the target is a directory and it is not empty,
the connection target does not exist or is unaccessible, or
an unspecified error occurs preventing deletion of the target.public void rename(String newName) throws IOException
IOException
. The
FileConnection instance object remains open and available for use,
referring now to the file or directory by its new name.
newName
- The new name of the file or directory. The name must
not contain any path specification; the file or directory
remains in its same directory as before this method call.
IOException
- if the connection's target does not exist, the
connection's target is not accessible, a file or directory
already exists by the newName
, or
newName
is an invalid filename for the platform
(e.g. contains characters invalid in a filename on the platform).
ConnectionClosedException
- if the connection is closed.
SecurityException
- if the security of the application does not
have write access to the connection's target.
IllegalModeException
- if the application does have write access
to the connection's target but has opened the connection in
Connector.READ
mode.
NullPointerException
- if newName
is
null
.
IllegalArgumentException
- if newName
contains any
path specification.public void truncate(long byteOffset) throws IOException
byteOffset
- the offset into the file from which truncation
occurs.
IOException
- if invoked on a directory or the file does not exist
or is not accessible.
ConnectionClosedException
- if the connection is closed.
SecurityException
- if the security of the application does not
have write access to the file.
IllegalModeException
- if the application does have write access
to the file but has opened the connection in
Connector.READ
mode.
IllegalArgumentException
- if byteOffset
is
less than zero.public void setFileConnection(String fileName) throws IOException
fileName
- name of the file or directory to which this
FileConnection is reset. The fileName must be one of the
values returned from the list()
method, or the string
".." to indicate the parent directory of the current
connection. The fileName must not contain any additional path
specification; i.e. the file or directory must reside within
the current directory.
NullPointerException
- if fileName
is
null
.
SecurityException
- if the security of the application does not
have the security access to the specified file or directory
as requested in the Connector.open method
invocation that originally opened this FileConnection.
IllegalArgumentException
- if fileName
contains any
path specification or does not yet exist.
IOException
- if the current FileConnection is opened on a file,
the connection's target is not accessible, or
fileName
is an invalid filename for the platform
(e.g. contains characters invalid in a filename on the platform).
ConnectionClosedException
- if the connection is closed.public String getName()
<directory>/or
<filename.extension>or if no file extension
<filename>
public String getPath()
getName()
can be appended to
this value to get a fully qualified path filename. The String resulting
from this method looks as follows:
/<root>/<directory>/
public String getURL()
file://<host>/<root>/<directory>/<filename.extension>or
file://<host>/<root>/<directory>/<directoryname>/
public long lastModified()
SecurityException
- if the security of the application does not
have read access for the connection's target.
IllegalModeException
- if the application does have read access
to the connection's target but has opened the connection in
Connector.WRITE
mode.
ConnectionClosedException
- if the connection is closed.
|
IM Profile | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |