waba.io
Class File

java.lang.Object
  |
  +--waba.io.Stream
        |
        +--waba.io.File

Direct Known Subclasses:

BufferedFile

public class File

extends Stream

File is a file or directory.

The File class will work in Windows CE or in a Palm OS >= 3.5, containing an expansion card. Use the isAvailable method to determine if the device has or not support for file systems.

Note that in Palm OS, writing to a storage card can be slower than writing to the main memory.

Here is an example showing data being read from a file:

 File file = new File("/temp/tempfile", File.READ_ONLY);
 if (!file.isOpen())
   return;
 byte b[] = new byte[10];
 file.readBytes(b, 0, 10);
 file.close();
 file = new File("/temp/tempfile", File.DONT_OPEN);
 file.delete();
 

Field Summary

static int	ATTR_ARCHIVE Used in the getAttributes and setAttributes method.
static int	ATTR_HIDDEN Used in the getAttributes and setAttributes method.
static int	ATTR_READ_ONLY Used in the getAttributes and setAttributes method.
static int	ATTR_SYSTEM Used in the getAttributes and setAttributes method.
static int	CREATE Create open mode.
static int	DONT_OPEN Don't open the file mode.
int	lastError On device, stores the last error.
protected java.lang.String	path The path that represents this file
static int	READ_ONLY Read-only open mode.
static int	READ_WRITE Read-write open mode.
static byte	TIME_ACCESSED Used in the getAttributes and setAttributes method.
static byte	TIME_ALL Used in the setTime method, in parameter whichTime.
static byte	TIME_CREATED Used in the getAttributes and setAttributes method.
static byte	TIME_MODIFIED Used in the getAttributes and setAttributes method.
static java.lang.String[]	winceVols These are the volumes that getCardVolume search to find the available one.
static int	WRITE_ONLY Write-only open mode.

Constructor Summary

File(java.lang.String path)
Opens a file in DONT_OPEN mode.

File(java.lang.String path, int mode)
Opens a file with the given name and mode, in the last available card number (if Palm OS).

File(java.lang.String path, int mode, int slot)
Opens a file with the given name, mode and in the given card number.

Method Summary

boolean	close() Closes the file.
boolean	createDir() Creates a directory.
boolean	delete() Deletes the file or directory.
boolean	exists() Returns true if the file exists and false otherwise.
void	finalize() Used by Jump.
int	getAttributes() Gets this file attributes.
static File	getCardVolume() Returns the volume File for the Windows CE and Pocket PC devices.
java.lang.String	getPath() Return the file's path.
int	getSize() Returns the size of the file in bytes.
Time	getTime(byte whichTime) Gets the time for the given time type.
static boolean	isAvailable() Returns true if a File System is available in the current PDA.
static boolean	isCardInserted(int slot) Can be used to verify if a card is inserted into the given slot.
boolean	isDir() Returns true if the file is a directory and false otherwise.
boolean	isOpen() Returns true if the file is open for reading or writing and false otherwise.
java.lang.String[]	listFiles() Lists the files contained in a directory.
int	readBytes(byte[] b, int off, int len) Reads bytes from the file into a byte array.
boolean	rename(java.lang.String path) Renames the file.
void	setAttributes(int attr) Sets this file attributes.
boolean	setPos(int pos) Sets the file pointer for read and write operations to the given position.
void	setTime(byte whichTime, Time time) Sets the time for the given time type.
int	writeBytes(byte[] b, int off, int len) Writes to the file.

Methods inherited from class java.lang.Object

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

Field Detail

path

protected java.lang.String path

The path that represents this file

lastError

public int lastError

On device, stores the last error. For WinCE, you must check the WINERROR.H file.

For Palm OS, the list of possible errors are described below:

BufferOverflow	10753
FileGeneric	10754
FileBadRef	10755
FileStillOpen	10756
FilePermissionDenied	10757
FileAlreadyExists	10758
FileEOF	10759
FileNotFound	10760
VolumeBadRef	10761
VolumeStillMounted	10762
NoFileSystem	10763
BadData	10764
DirNotEmpty	10765
BadName	10766
VolumeFull	10767
Unimplemented	10768
NotADirectory	10769
IsADirectory	10770
DirectoryNotFound	10771
NameShortened	10772

DONT_OPEN

public static final int DONT_OPEN

Don't open the file mode.

READ_ONLY

public static final int READ_ONLY

Read-only open mode.

WRITE_ONLY

public static final int WRITE_ONLY

Write-only open mode. In some systems (non-Palm), it may erase the file!

READ_WRITE

public static final int READ_WRITE

Read-write open mode.

CREATE

public static final int CREATE

Create open mode. Used to create a file if one does not exist.

TIME_ALL

public static final byte TIME_ALL

Used in the setTime method, in parameter whichTime. This sets all times

TIME_CREATED

public static final byte TIME_CREATED

Used in the getAttributes and setAttributes method. These values are platform independent, and can be ORed together in the setTime method.

TIME_MODIFIED

public static final byte TIME_MODIFIED

Used in the getAttributes and setAttributes method. These values are platform independent, and can be ORed together in the setTime method.

TIME_ACCESSED

public static final byte TIME_ACCESSED

Used in the getAttributes and setAttributes method. These values are platform independent, and can be ORed together in the setTime method.

ATTR_ARCHIVE

public static final int ATTR_ARCHIVE

Used in the getAttributes and setAttributes method. These values are platform independent.

ATTR_HIDDEN

public static final int ATTR_HIDDEN

Used in the getAttributes and setAttributes method. These values are platform independent.

ATTR_READ_ONLY

public static final int ATTR_READ_ONLY

Used in the getAttributes and setAttributes method. These values are platform independent.

ATTR_SYSTEM

public static final int ATTR_SYSTEM

Used in the getAttributes and setAttributes method. These values are platform independent.

winceVols

public static java.lang.String[] winceVols

These are the volumes that getCardVolume search to find the available one.

Constructor Detail

File

public File(java.lang.String path,
            int mode,
            int slot)

Opens a file with the given name, mode and in the given card number. If mode is CREATE, the file will be created if it does not exist. The DONT_OPEN mode allows the exists(), rename(), delete(), listDir(), createDir() and isDir() methods to be called without requiring the file to be open for reading or writing.

Note that the filename must not contain accentuated characters. Also, the slash / MUST be the path separator. Note also that some OSes may not allow the creation of files in the ROOT directory.

Parameters:

path - the file's path

mode - one of DONT_OPEN, READ_ONLY, WRITE_ONLY, READ_WRITE or CREATE

slot - The slot number. This currently works only on Palm OS devices, because other OSes use a different approach to specify the card. The number may be -1 to use the last available card, or a number between 0 and the number of cards supported by the device. Some new Palm OS devices have slot 0 as the main non-volatile memory, and 1 and so on for external memory cards. You can find the available slots using this code:

   for (int i = 0; i < 255; i++)
      if (File.isCardInserted(i))
         add(new Label("found "+i),LEFT,AFTER); // Zire 22 returns 1 only
 

Since:

SuperWaba 5.52

File

public File(java.lang.String path,
            int mode)

Opens a file with the given name and mode, in the last available card number (if Palm OS). If mode is CREATE, the file will be created if it does not exist. The DONT_OPEN mode allows the exists(), rename(), delete(), listDir(), createDir() and isDir() methods to be called without requiring the file to be open for reading or writing.

Note that the filename must not contain accentuated characters. Also, the slash / MUST be the path separator. Note also that some OSes may not allow the creation of files in the ROOT directory.

Parameters:

path - the file's path

mode - one of DONT_OPEN, READ_ONLY, WRITE_ONLY, READ_WRITE or CREATE

File

public File(java.lang.String path)

Opens a file in DONT_OPEN mode. This constructor is useful for directory manipulation and/or check if file exists. No read/write operation can be done with a file created in this mode.

Method Detail

isAvailable

public static boolean isAvailable()

Returns true if a File System is available in the current PDA. In Windows CE and Desktop, this always returns true. In Palm OS, it will depend if the file has a external card slot (Secure Digital, Smart Media, etc). Using other methods in this class without first checking if this class is available in the target device will simply reset it.

isCardInserted

public static boolean isCardInserted(int slot)

Can be used to verify if a card is inserted into the given slot. Note that isAvailable must be checked prior to this method.

Parameters:

slot - The slot number, or -1 to use the last slot number (which, in most devices, will be the only slot available).

Since:

SuperWaba 5.52

close

public boolean close()

Closes the file. Returns true if the operation is successful and false otherwise.

Overrides:

close in class Stream

createDir

public boolean createDir()

Creates a directory. Returns true if the operation is successful and false otherwise.

delete

public boolean delete()

Deletes the file or directory. Returns true if the operation is successful and false otherwise. After this operation, this File object is invalid.

exists

public boolean exists()

Returns true if the file exists and false otherwise.

getSize

public int getSize()

Returns the size of the file in bytes. If the file is a root directory (always "/", never "\\"), it returns the ammount of free space in bytes of the card/file system (does not work in JDK). If the total amount is greater than 1 Gigabyte, 1073741824 is returned. In other cases, if the file is not opened, 0 will be returned.

getPath

public java.lang.String getPath()

Return the file's path.

isDir

public boolean isDir()

Returns true if the file is a directory and false otherwise.

isOpen

public boolean isOpen()

Returns true if the file is open for reading or writing and false otherwise. This can be used to check if opening or creating a file was successful.

Overrides:

isOpen in class Stream

listFiles

public java.lang.String[] listFiles()

Lists the files contained in a directory. The strings returned are the names of the files and directories contained within this directory. This method returns null if the directory can't be read or if the operation fails. Volume labels are returned between [], and paths have a / after the name.

readBytes

public int readBytes(byte[] b,
                     int off,
                     int len)

Reads bytes from the file into a byte array. Returns the number of bytes actually read or -1 if an error prevented the read operation from occurring. After the read is complete, the location of the file pointer (where read and write operations start from) is advanced the number of bytes read.

Overrides:

readBytes in class Stream

Parameters:

b - the byte array to read data into

off - the offset position in the array

len - the number of bytes to read

rename

public boolean rename(java.lang.String path)

Renames the file. You must give the full directory specification for the file, to keep compatibility between all platforms. WinCE platform lets you move a file using rename, while Palm OS does not let you move the file. Returns true if the renaming was successful and false otherwise. After this operation, this File object is invalid.

setPos

public boolean setPos(int pos)
               throws IOError

Sets the file pointer for read and write operations to the given position. The position passed is an absolute position, in bytes, from the beginning of the file. To set the position to just after the end of the file, you can call:

 file.setPos(file.getSize());
 

Note: if you plan to change the file size using setPos, you must write something on the new size to effectively change the size. For example, in some devices if you call setPos and then read (assuming that the new pos is past the end of the file, the read method will fail. Here's a code that will change the size for sure:

private static byte[] zeros = new byte[4096];
public void setSize(int newSize)
{
int size = f.getSize();
f.setPos(newSize-1); // note: setPos(1) makes the file 2 bytes long (0, 1)
f.setPos(size);
for (int dif = newSize - size,n=0; dif > 0; dif -= n)
n = f.writeBytes(zeros, 0, dif > zeros.length ? zeros.length : dif);
}
 

Returns:

True if the operation is successful and false otherwise.

Throws:

IOError - Starting in SuperWaba version 5.8, an IOError may be thrown when the positioning fails and if Settings.useExceptions is true.

writeBytes

public int writeBytes(byte[] b,
                      int off,
                      int len)

Writes to the file. Returns the number of bytes written or -1 if an error prevented the write operation from occurring. After the write is complete, the file pointer (where read and write operations start from) is advanced the number of bytes written.

Overrides:

writeBytes in class Stream

Parameters:

b - the byte array to write data from

off - the offset position in the byte array

len - the number of bytes to write

setAttributes

public void setAttributes(int attr)

Sets this file attributes. This method does not work on desktop. The file must be opened in a mode different of DONT_OPEN.

Parameters:

attr - one ore more ATTR_xxx constants ORed together. Values different from the ATTR_xxx constants are simply ignored.

getAttributes

public int getAttributes()

Gets this file attributes. See the ATTR_xxx constants, which can be ORed together. This method does not work on desktop. The file must be opened in a mode different of DONT_OPEN.

Returns:

-1 if failure, otherwise the attributes ORed together.

setTime

public void setTime(byte whichTime,
                    Time time)

Sets the time for the given time type. See the TIME_xxx constants. This method does not work on desktop. The file must be opened in a mode different of DONT_OPEN.

getTime

public Time getTime(byte whichTime)

Gets the time for the given time type. See the TIME_xxx constants. This method does not work on desktop. Note that the constants in this method CANNOT be ORed together; in other words, this method only returns one time in each call. The file must be opened in a mode different of DONT_OPEN.

getCardVolume

public static File getCardVolume()

Returns the volume File for the Windows CE and Pocket PC devices. In these devices, the volume has a special folder name, but since there's no system call that informs this, we must just test the existence of each folder, returning the first one that exists. You can set the winceVols string to the ones you want to be searched.

Returns:

The File object which references the volume, ended with backslash, or null if none found.

finalize

public void finalize()

Used by Jump. Does nothing in the SW VM

Overrides:

finalize in class java.lang.Object