ch.aplu.gidlet
Class MFile

java.lang.Object
  ch.aplu.gidlet.MFile

public class MFile
extends java.lang.Object

Class to access files or directories that are located on removable media and/or file systems on a device. Integrates the the file connection package (JSR 75) into the Gidlet framework, in particular errors are not reported by exceptions but by boolean return values. Not all mobile devices support JSR 75. Use isFileConnectionSupported() for dynamic detection of support or consult the manufacture technical specifations. File read and write operations are performed in a separate thread. For all methods, except getDataInputStream(), getDataOutputStream(), openConnection(). the following schema is used:
- close an already opened file connection
- open a new file connection
- perform operation
- close the file connection To suppress the question that the emulator ask about accessing the file system change in file
- c:\Documents and Settings\\j2mewtk\2.5.2\appdb\_policy.txt
(for WTK 2.5.2 and NetBeans 5.5.1 up)

- wtkroot\appdb\_policy.txt
(for WTK 2.5.1)

existing lines

blanket(oneshot): read_user_data_access
blanket(oneshot): write_user_data_access

to

allow: read_user_data_access
allow: write_user_data_access


When using the WTK emulator with the DefaultColorPhone the home directory of the emulated file system resides on
- userhome\j2mewtk\2.5.2\appdb\DefaultColorPhone\filesystem
(for WTK 2.5.2 and NetBeans 5.5.1 up)

- wtkroot\appdb\DefaultColorPhone\filesystem
(for WTK 2.5.1)
Only one file system root (emulated device) is visible (name: root1/).

Constructor Summary

MFile()
Create a MFile instance with empty path.

MFile(java.lang.String path)
Creates a MFile instance with given path.

Method Summary

boolean	append(java.lang.String data) Appends string data to the end of the text file.
boolean	canRead() Checks if the file/directory is readable.
boolean	canWrite() Checks if the file/directory is writable.
boolean	clear() Clears all data.
boolean	createDir() Creates a directory corresponding to the MFile's path.
boolean	createFile() Creates a file with zero length.
boolean	exists() Checks if the path corresponds to an existing file or directory.
boolean	findFirst() Starts enumerating the files in the given directory.
boolean	findFirstRoot() Starts enumerating the file system roots.
boolean	findNext() Continues enumerating the files after calling findFirst() Be aware of the side effect, that the path is changed, if any file or subdirectory is found.
boolean	findNextRoot() Continues enumerating the roots after calling findFirstRoot() Be aware of the side effect, that the path is changed, if a root is found.
long	getAvailableSpace() Determines the free space on the file system, where the MFile's path resides on.
java.io.DataInputStream	getDataInputStream() Opens a DataInputStream used to read primitive data types from a file.
java.io.DataOutputStream	getDataOutputStream() Opens a DataOutputStream used to write primitive data types to a file.
long	getFileSize() Gets the size of the file.
java.io.InputStream	getInputStream() Opens a InputStream used to read data from a file.
java.lang.String	getName() Gets file name part of the path.
java.io.OutputStream	getOutputStream() Opens an OutputStream used to write data to a file.
java.lang.String	getPath() Gets fully qualified path of file.
java.lang.String	getURL() Gets fully qualified URL path of file.
long	getUsedSpace(boolean includeSubDirs) Determines the amount of space used by all files on the file system, where the MFile's path resides on.
boolean	isDirectory() Checks if the path corresponds to an existing directory.
boolean	isFile() Checks if the path corresponds to an existing file (not a directory).
static boolean	isFileConnectionSupported() Checks if FileConnection (JSR 75) is supported.
boolean	isHidden() Checks if the file/directory is hidden.
javax.microedition.io.file.FileConnection	openConnection() Closes an eventually opened connection and open a new one.
java.lang.String	read() Reads content of a text file.
void	releaseConnection() Releases all allocated resources (FileConnection, DataInputStream, DataOutputStream).
boolean	remove() Removes file or directory.
boolean	rename(java.lang.String newName) Renames file or directory.
boolean	setHidden(boolean hidden) Sets the hidden attribute of file or directory to the given value.
void	setPath(java.lang.String path) Sets fully qualified path of file.
boolean	setReadable(boolean readable) Sets the read attribute of file or directory to the given value.
boolean	setWritable(boolean writable) Sets the write attribute of file or directory to the given value.
boolean	write(java.lang.String data) Writes string data to the text file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MFile

public MFile()

Create a MFile instance with empty path.

MFile

public MFile(java.lang.String path)

Creates a MFile instance with given path. path is fully qualified with / separator. Directory pathes must end with a /
e.g.
root1/Pictures/image1.jpg : path to file
c:/Games/ : path to directory
No connection to the given file/directory is yet established.

Parameters:

path - of file or directory

Method Detail

setPath

public void setPath(java.lang.String path)

Sets fully qualified path of file. (Also modifies URL path.) No connection to the given file/directory is yet established.

getPath

public java.lang.String getPath()

Gets fully qualified path of file.

Returns:

path

getName

public java.lang.String getName()

Gets file name part of the path.

Returns:

the file name part or empty string,if path is a directory.

getURL

public java.lang.String getURL()

Gets fully qualified URL path of file. The URL path is composed as "file:///" + path.

Returns:

URL path

isFileConnectionSupported

public static boolean isFileConnectionSupported()

Checks if FileConnection (JSR 75) is supported.

Returns:

true, if supported, otherwise false

getDataOutputStream

public java.io.DataOutputStream getDataOutputStream()

Opens a DataOutputStream used to write primitive data types to a file. Uses the write-Methods to write to the file. The file connection and the file stream remain open, until releaseConnection() (or another file operation method) is called. If the stream is already open, nothing happens.

Returns:

a reference to the opened stream or null, if operation fails.

See Also:

releaseConnection()

getOutputStream

public java.io.OutputStream getOutputStream()

Opens an OutputStream used to write data to a file. The file connection and the file stream remain open, until releaseConnection() (or another file operation method) is called. If the stream is already open, nothing happens.

Returns:

a reference to the opened stream or null, if operation fails.

See Also:

releaseConnection()

getDataInputStream

public java.io.DataInputStream getDataInputStream()

Opens a DataInputStream used to read primitive data types from a file. Uses the read-Methods to read from the file and catch the EOFException to stop reading. The file connection and the file stream remain open, until releaseConnection() (or another file operation method) is called. If the stream is already open, nothing happens.

Returns:

a reference to the opened stream or null, if operation fails.

See Also:

releaseConnection()

getInputStream

public java.io.InputStream getInputStream()

Opens a InputStream used to read data from a file. The file connection and the file stream remain open, until releaseConnection() (or another file operation method) is called. If the stream is already open, nothing happens.

Returns:

a reference to the opened stream or null, if operation fails.

See Also:

releaseConnection()

write

public boolean write(java.lang.String data)

Writes string data to the text file. If the file does not exist, it will be created. If the file exists, all data is cleared. Runs in a separate thread to improve performance. All resources are released when finishing.

Returns:

true, if successful, false if operation fails

append

public boolean append(java.lang.String data)

Appends string data to the end of the text file. If the file does not exist, it will be created. Runs in a separate thread to improve performance, but waits for the thread to terminate. All resources are released when finishing.

Returns:

true, if successful, false if operation fails

read

public java.lang.String read()

Reads content of a text file. Runs in a separate thread to improve performance, but waits for the thread to terminate. All resources are released when finishing.

Returns:

content as string, empty if file has zero length, null if operation fails

findFirst

public boolean findFirst()

Starts enumerating the files in the given directory. Follow this procedure:
1. Set the path to the directory where files and subdirectories will be enumerated.
2. Call findFirst(); if it returns true, the path is set to the first file/subdirectory. Otherwise there is no file/subdirectory and you can't proceed.
3. Keep calling findNext() until it returns false, meaning there are no more files/directories. After every successful findNext() call, the path is set to the next file/subdirectory.
Be aware of the side effect, that the path is changed, if any file or subdirectory is found.

Returns:

true, if the given directory contains at least one file or subdirectory, false otherwise (the path is unchanged).

See Also:

findNext()

findNext

public boolean findNext()

Continues enumerating the files after calling findFirst() Be aware of the side effect, that the path is changed, if any file or subdirectory is found.

Returns:

true, if the search for a next file or subdirectory is successful, false, if there is no more file/subdirectory (the path is unchanged) or no preceding findFirst() was called.

See Also:

findFirst()

findFirstRoot

public boolean findFirstRoot()

Starts enumerating the file system roots. Follow this procedure:
1. Set the path to "" or any other value (not used)
2. Call findFirstRoot(); if it returns true, the path is set to the first detected root. Otherwise no root is found and you can't proceed.
3. Keep calling findNextRoot() until it returns false, meaning there are no more roots. After every successful findNext() call, the path is set to the next root.
Be aware of the side effect, that the path is changed, if any root is found.

Returns:

true, if the system reports at least one root, false otherwise (the path is unchanged).

See Also:

findNextRoot()

findNextRoot

public boolean findNextRoot()

Continues enumerating the roots after calling findFirstRoot() Be aware of the side effect, that the path is changed, if a root is found.

Returns:

true, if the search for a next root is successful, false, if there are no more roots (the path is unchanged) or no preceding findFirstRoot() was called.

See Also:

findFirstRoot()

exists

public boolean exists()

Checks if the path corresponds to an existing file or directory.

Returns:

true, if the file/directory exists, otherwise false

isFile

public boolean isFile()

Checks if the path corresponds to an existing file (not a directory).

Returns:

true, if the file exists, otherwise false

isDirectory

public boolean isDirectory()

Checks if the path corresponds to an existing directory.

Returns:

true, if the directory exists, otherwise false

remove

public boolean remove()

Removes file or directory. To remove a directory, it must be empty.

Returns:

true, if successful, false, if file or directory does not exist or operation fails

rename

public boolean rename(java.lang.String newName)

Renames file or directory. The given name must be a valid file or directory name without any further path information. The MFile's path is not modified.

Returns:

true, if successful, false, if operation fails

clear

public boolean clear()

Clears all data. After clearing the filesize is 0.

Returns:

true, if successful, false, if operation fails

createDir

public boolean createDir()

Creates a directory corresponding to the MFile's path. Only one directory level is allowed. A directory path must end with /.

Returns:

true, if successful, false, if operation fails

createFile

public boolean createFile()

Creates a file with zero length. All directories in the MFile's path must exist, before the file may be created. If the file already exists, it is deleted first.

Returns:

true, if successful, otherwise false

canRead

public boolean canRead()

Checks if the file/directory is readable.

Returns:

true, if readable, otherwise false.

canWrite

public boolean canWrite()

Checks if the file/directory is writable.

Returns:

true, if writable, otherwise false.

isHidden

public boolean isHidden()

Checks if the file/directory is hidden.

Returns:

true, if hidden, otherwise false.

setHidden

public boolean setHidden(boolean hidden)

Sets the hidden attribute of file or directory to the given value.

Returns:

true, if successful, otherwise false.

setReadable

public boolean setReadable(boolean readable)

Sets the read attribute of file or directory to the given value.

Returns:

true, if successful, otherwise false.

setWritable

public boolean setWritable(boolean writable)

Sets the write attribute of file or directory to the given value.

Returns:

true, if successful, otherwise false.

getFileSize

public long getFileSize()

Gets the size of the file.

Returns:

File size in bytes or -1 if operation fails

getAvailableSpace

public long getAvailableSpace()

Determines the free space on the file system, where the MFile's path resides on.

Returns:

the free space in bytes or -1 when operation fails

getUsedSpace

public long getUsedSpace(boolean includeSubDirs)

Determines the amount of space used by all files on the file system, where the MFile's path resides on. If includeSubDirs is true, include all subdirectories. The MFile's path must point to an existing directory (terminated with /).

Returns:

the amount of bytes used by the file system, -1 of operation fails.

openConnection

public javax.microedition.io.file.FileConnection openConnection()

Closes an eventually opened connection and open a new one. Calls releaseConnection() to close the connection.

Returns:

Reference to the FileConnection or null, if operation fails

See Also:

releaseConnection()

releaseConnection

public void releaseConnection()

Releases all allocated resources (FileConnection, DataInputStream, DataOutputStream). If resources are not actually in use, nothing happens.