com.sun.spot.flashmanagement
Class FlashFile

java.lang.Object
  com.sun.spot.flashmanagement.FlashFile

public class FlashFile
extends Object

FlashFile

This class is the main entry point to the flash memory filing system. This class is modelled on java.io.File from j2se. As for File in j2se, a FlashFile does not represent the file itself, but merely a handle or name for a file. Creating a FlashFile object does not create the file.

A flash-based file comprises one or more sectors of flash memory. An underlying flash manager takes care of allocating sectors for files. Allocation is recorded in a File Allocation Table (FAT) managed by the flash manager. The flash manager, which is not publicly accessible, also holds file descriptors for each file.

One important difference between File and FlashFile is that when creating a new file the size of the file must be specified, and files are not extended automatically.

For some uses (e.g. storing suites) it is important that a file appears to occupy a contiguous range of memory addresses and starts at a specific address. Such a file is called a "mapped" file, and the flash filing system uses the MMU to map the file's sectors to the correct addresses. To make a file mapped use setVirtualAddress(int) and then map().

Rather than deleting a file and thereby releasing the sectors it occupies, a file can be marked as "obsolete". The space occupied by obsolete files is reclaimed at the next reboot. This is useful if the file contains the bytecodes of an active suite.

CAVEATS

The current implementation does not provide file locking: it is possible for two users simultaneously to access the same file, possibly with disastrous consequences.

A FlashFile object does not hold on to a pointer to the underlying file descriptor but gets it from the flash manager each time it is required. Acquiring a reference to a file descriptor is an expensive operation (taking about 15ms on an eSPOT), so you should avoid repeatedly calling FlashFile operations that need access to it, such as getAllocatedSpace() or length().

Field Summary

static int	FAT_IDENTIFIER_V1
static int	FAT_IDENTIFIER_V2
static int	FAT_IDENTIFIER_V3
static long	FIRST_FILE_VIRTUAL_ADDRESS The lowest valid virtual address that can be allocated to a file
static long	LAST_FILE_VIRTUAL_ADDRESS The highest valid virtual address that can be allocated to a file
static int	SPOT_GLOBAL_FLASH_MANAGER The index used with SpotGlobals to access the globally shared FlashManager
static int	SPOT_GLOBAL_NOR_FLASH_SECTOR_FACTORY The index used with SpotGlobals to access the globally shared NorFlashSectorFactory
static int	VIRTUAL_ADDRESS_FILE_SPACING The size of the virtual address space allocated to a mapped file

Constructor Summary

FlashFile(String name)
Create a FlashFile with the specified name.

Method Summary

void	commit() Ensure all changes to this file's descriptor are written persistently.
boolean	createNewFile(int size) Create a new file of the specified size, whose name is the name of this FlashFile object.
void	delete() Delete the file with this name
boolean	exists() Check whether a file with this name exists
int	getAllocatedSpace() Determine the space allocated for the file with this name.
String	getComment() Get the comment for this file
static IFAT	getFAT() Get a read-only representation of the FAT
int	getFirstSectorBaseAddress() For test purposes only
String	getName() Get the name of this file
static int	getUnusedVirtualAddress() Returns an unused virtual address.
int	getVirtualAddress() Get the virtual address of a mapped file
boolean	isAddressed() Check whether this file has a virtual address.
boolean	isMapped() Check whether this file is mapped.
boolean	isObsolete() Check whether the file with this name is obsolete
long	lastModified() Get the time at which this file was last modified
int	length() Get the length of the file with this name.
void	map() Cause the file with this name to become a mapped file.
boolean	renameTo(FlashFile dest) Rename the file with this name so that it has a different name
static void	resetFAT() Overwrite the existing FAT with a new empty one.
void	setComment(String comment) Set a comment for this file
static void	setNorFlashSectorFactory(INorFlashSectorFactory norFlashSectorFactory) Set the INorFlashSectorFactory to be used by FlashFile when creating a FlashManager.
void	setObsolete(boolean b) Set whether or not the file with this name is obsolete.
void	setVirtualAddress(int virtualAddress) Set the virtual address that the file gets mapped to.

Methods inherited from class java.lang.Object

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

Field Detail

SPOT_GLOBAL_FLASH_MANAGER

public static final int SPOT_GLOBAL_FLASH_MANAGER

The index used with SpotGlobals to access the globally shared FlashManager

See Also:

Constant Field Values

SPOT_GLOBAL_NOR_FLASH_SECTOR_FACTORY

public static final int SPOT_GLOBAL_NOR_FLASH_SECTOR_FACTORY

The index used with SpotGlobals to access the globally shared NorFlashSectorFactory

See Also:

Constant Field Values

VIRTUAL_ADDRESS_FILE_SPACING

public static final int VIRTUAL_ADDRESS_FILE_SPACING

The size of the virtual address space allocated to a mapped file

See Also:

Constant Field Values

FIRST_FILE_VIRTUAL_ADDRESS

public static final long FIRST_FILE_VIRTUAL_ADDRESS

The lowest valid virtual address that can be allocated to a file

See Also:

Constant Field Values

LAST_FILE_VIRTUAL_ADDRESS

public static final long LAST_FILE_VIRTUAL_ADDRESS

The highest valid virtual address that can be allocated to a file

See Also:

Constant Field Values

FAT_IDENTIFIER_V1

public static final int FAT_IDENTIFIER_V1

See Also:

Constant Field Values

FAT_IDENTIFIER_V2

public static final int FAT_IDENTIFIER_V2

See Also:

Constant Field Values

FAT_IDENTIFIER_V3

public static final int FAT_IDENTIFIER_V3

See Also:

Constant Field Values

Constructor Detail

FlashFile

public FlashFile(String name)

Create a FlashFile with the specified name. Note that this does not create the file itself - call createNewFile(int) to do that.

Parameters:

name - the name of the file

Method Detail

setNorFlashSectorFactory

public static void setNorFlashSectorFactory(INorFlashSectorFactory norFlashSectorFactory)
                                     throws IOException

Set the INorFlashSectorFactory to be used by FlashFile when creating a FlashManager. It is only necessary to call this method if you want a factory other than the default one (which allocates sectors that are read and written using the standard flash memory driver).

Parameters:

norFlashSectorFactory - the factory to use

Throws:

IOException

resetFAT

public static void resetFAT()
                     throws IOException

Overwrite the existing FAT with a new empty one. Use with care as existing FlashFiles will be in an inconsistent state

Throws:

IOException

getFAT

public static IFAT getFAT()

Get a read-only representation of the FAT

Returns:

a read-only representation of the FAT

getUnusedVirtualAddress

public static int getUnusedVirtualAddress()
                                   throws IOException

Returns an unused virtual address.

Returns:

The virtual address

Throws:

IOException

createNewFile

public boolean createNewFile(int size)
                      throws InsufficientFlashMemoryException

Create a new file of the specified size, whose name is the name of this FlashFile object.

Parameters:

size - the size in bytes of the file to create

Returns:

true if the file was created or false if it could not be created because it already existed

Throws:

InsufficientFlashMemoryException - if the space requested cannot be allocated

exists

public boolean exists()

Check whether a file with this name exists

Returns:

true if a file with this name exsits, false otherwise

delete

public void delete()
            throws IOException

Delete the file with this name

Throws:

IOException

length

public int length()
           throws IOException

Get the length of the file with this name. Warning: this operation accesses the file descriptor and will be slow - see class comment.

Returns:

the length in bytes of the valid portion of the file with this name

Throws:

IOException

commit

public void commit()
            throws IOException

Ensure all changes to this file's descriptor are written persistently. Note that this operation does not force data written to a FlashFileOutputStream to be written persistently: the FlashFileOutputStream must be flushed or closed separately.

Throws:

IOException

setVirtualAddress

public void setVirtualAddress(int virtualAddress)
                       throws IOException

Set the virtual address that the file gets mapped to. This mapping will take place at the next reboot or when map() is invoked. The virtual address must be one of the valid addresses defined by FIRST_FILE_VIRTUAL_ADDRESS, LAST_FILE_VIRTUAL_ADDRESS and VIRTUAL_ADDRESS_FILE_SPACING.

Parameters:

virtualAddress - the virtual address for the file, or 0 if it should not be a mapped file

Throws:

IOException

setComment

public void setComment(String comment)
                throws IOException

Set a comment for this file

Parameters:

comment - the comment to be attached to the descriptor of the file

Throws:

IOException

getVirtualAddress

public int getVirtualAddress()
                      throws IOException

Get the virtual address of a mapped file

Returns:

the virtual address of the file, or 0 if it is not a mapped file

Throws:

IOException

getComment

public String getComment()
                  throws IOException

Get the comment for this file

Returns:

the comment attached to the file's descriptor

Throws:

IOException

lastModified

public long lastModified()
                  throws IOException

Get the time at which this file was last modified

Returns:

the time (as returned by System.currentTimeMillis()) at which this file was last modified.

Throws:

IOException

setObsolete

public void setObsolete(boolean b)
                 throws IOException

Set whether or not the file with this name is obsolete. The space occupied by an obsolete file is reclaimed at the next reboot.

Parameters:

b - true if this file is to be marked obsolete, false if it is not

Throws:

IOException

isObsolete

public boolean isObsolete()
                   throws IOException

Check whether the file with this name is obsolete

Returns:

true if this file is marked obsolete, false if it is not

Throws:

IOException

map

public void map()
         throws IOException

Cause the file with this name to become a mapped file. The file's sectors will be mapped so that the file occupies a contiguous range of memory addresses, starting with its defined virtual address. If map() is called before a virtual address has been specified using setVirtualAddress(int) then a free virtual address will be allocated (and can be discovered after the map() call using getVirtualAddress().

Throws:

IOException

isMapped

public boolean isMapped()
                 throws IOException

Check whether this file is mapped.

Returns:

true if this file is mapped to a virtual address

Throws:

IOException

isAddressed

public boolean isAddressed()
                    throws IOException

Check whether this file has a virtual address.

Returns:

true if this file has a virtual address

Throws:

IOException

getAllocatedSpace

public int getAllocatedSpace()
                      throws IOException

Determine the space allocated for the file with this name. Warning: this operation accesses the file descriptor and will be slow - see class comment.

Returns:

the space in bytes allocated for this file

Throws:

IOException

getName

public String getName()

Get the name of this file

Returns:

the name of this file

renameTo

public boolean renameTo(FlashFile dest)
                 throws IOException

Rename the file with this name so that it has a different name

Parameters:

dest - the new name for the file

Returns:

true if the file was renamed, false if a file with the new name already existed

Throws:

IOException

getFirstSectorBaseAddress

public int getFirstSectorBaseAddress()
                              throws IOException

For test purposes only

Throws:

IOException