Package edu.caltech.nanodb.storage

Interface FileManager

All Known Implementing Classes:

FileManagerImpl

public interface FileManager

This interface specifies all operations that file managers must provide.

Method Summary

Modifier and Type	Method	Description
void	closeDBFile(DBFile dbFile)	Closes the underlying data file.
DBFile	createDBFile(java.lang.String filename, DBFileType type, int pageSize)	This method creates a new database file in the directory used by the storage manager.
void	deleteDBFile(DBFile dbFile)	Deletes the specified database file.
void	deleteDBFile(java.io.File f)	Deletes the specified database file.
void	deleteDBFile(java.lang.String filename)	Deletes the database file with the specified filename from the storage manager's directory.
boolean	fileExists(java.lang.String filename)	Returns true if the specified file exists, or false otherwise.
java.io.File[]	getDBFiles()	Returns an array of the files in the database.
boolean	loadPage(DBFile dbFile, int pageNo, byte[] buffer)	Loads a page from the underlying data file, and returns a new DBPage object containing the data.
boolean	loadPage(DBFile dbFile, int pageNo, byte[] buffer, boolean create)	Loads a page from the underlying data file, and returns a new DBPage object containing the data.
DBFile	openDBFile(java.lang.String filename)	This method opens a database file, and reads in the file's type and page size from the first two bytes of the first page.
boolean	renameDBFile(DBFile dbFile, java.lang.String newFilename)	Attempts to rename the specified DBFile to a new filename.
void	savePage(DBFile dbFile, int pageNo, byte[] buffer)	Saves a page to the DB file, and then clears the page's dirty flag.
void	syncDBFile(DBFile dbFile)	This method ensures that all file-writes on the specified DB-file have actually been synchronized to the disk.

Method Detail

getDBFiles

java.io.File[] getDBFiles()

Returns an array of the files in the database.

Returns:

list of database files

fileExists

boolean fileExists(java.lang.String filename)

Returns true if the specified file exists, or false otherwise.

Parameters:

filename - the name of the file to check for existence

Returns:

true if the file exists, or false otherwise

createDBFile

DBFile createDBFile(java.lang.String filename,
                    DBFileType type,
                    int pageSize)

This method creates a new database file in the directory used by the storage manager. An exception is thrown if the file already exists.

Parameters:

filename - the name of the file to open to create the database file

type - the type of database file being created

pageSize - the page size to use when reading and writing the file

Returns:

a new database file object for the newly created file

Throws:

FileSystemException - if the specified file already exists, or if the file can't be created for some reason

java.lang.IllegalArgumentException - if the page size is not valid

renameDBFile

boolean renameDBFile(DBFile dbFile,
                     java.lang.String newFilename)

Attempts to rename the specified DBFile to a new filename. If successful, the DBFile object itself is updated with a new File object reflecting the new name. If failure, the DBFile object is left untouched.

Parameters:

dbFile - the database file to rename

newFilename - the new name to give to the database file

Returns:

true if the rename succeeded, or false otherwise.

openDBFile

DBFile openDBFile(java.lang.String filename)

This method opens a database file, and reads in the file's type and page size from the first two bytes of the first page. The method uses the RandomAccessFile.readUnsignedShort() method to read the page size from the data file when it is opened.

Parameters:

filename - the name of the database file to open

Returns:

the successfully opened database file, or null if the file doesn't exist

loadPage

boolean loadPage(DBFile dbFile,
                 int pageNo,
                 byte[] buffer,
                 boolean create)

Loads a page from the underlying data file, and returns a new DBPage object containing the data. The create flag controls whether an error is propagated, if the requested page is past the end of the file. (Note that if a new page is created, the file's size will not reflect the new page until it is actually written to the file.)

This function does no page caching whatsoever. Requesting a particular page multiple times will return multiple page objects, with data loaded from the file each time.

Parameters:

dbFile - the database file to load the page from

pageNo - the number of the page to load

create - a flag specifying whether the page should be created if it doesn't already exist

Returns:

true if the page's contents were successfully loaded, or false otherwise.

Throws:

java.lang.IllegalArgumentException - if the page number is negative, or if the buffer is not the same length as the file's page-size.

loadPage

boolean loadPage(DBFile dbFile,
                 int pageNo,
                 byte[] buffer)

Loads a page from the underlying data file, and returns a new DBPage object containing the data. This method always reports an EOFException if the specified page is past the end of the database file.

This function does no page caching whatsoever. Requesting a particular page multiple times will return multiple page objects, with data loaded from the file each time.

(This method is simply a wrapper of loadPage(DBFile, int, byte[], boolean), passing false for create.)

Parameters:

dbFile - the database file to load the page from

pageNo - the number of the page to load

Returns:

true if the page's contents were successfully loaded, or false otherwise.

Throws:

java.lang.IllegalArgumentException - if the page number is negative, or if the buffer is not the same length as the file's page-size.

savePage

void savePage(DBFile dbFile,
              int pageNo,
              byte[] buffer)

Saves a page to the DB file, and then clears the page's dirty flag. Note that the data might not actually be written to disk until a sync operation is performed.

Parameters:

dbFile - the data file to write to

pageNo - the page number to write the buffer to

buffer - the data to write back to the page

Throws:

java.lang.IllegalArgumentException - if the page number is negative, or if the buffer is not the same length as the file's page-size.

syncDBFile

void syncDBFile(DBFile dbFile)

This method ensures that all file-writes on the specified DB-file have actually been synchronized to the disk. Note that even after a call to savePage(edu.caltech.nanodb.storage.DBFile, int, byte[]), the filesystem may postpone the write for various reasons, or disks may also buffer the write operations in order to optimize their storage to disk. This method ensures that any buffered writes will actually be written to the disk.

Parameters:

dbFile - the database file to synchronize

Throws:

FileSystemException - if the synchronization operation cannot be guaranteed successful, if some other IO problem occurs

closeDBFile

void closeDBFile(DBFile dbFile)

Closes the underlying data file. Obviously, subsequent read or write attempts will fail after this method is called.

Parameters:

dbFile - the database file to close

Throws:

FileSystemException - if the file cannot be closed for some reason

deleteDBFile

void deleteDBFile(java.lang.String filename)

Deletes the database file with the specified filename from the storage manager's directory.

Parameters:

filename - the name of the file to delete

Throws:

FileSystemException - if the file cannot be deleted for some reason

deleteDBFile

void deleteDBFile(java.io.File f)

Deletes the specified database file.

Parameters:

f - the file to delete

Throws:

FileSystemException - if the file cannot be deleted for some reason

deleteDBFile

void deleteDBFile(DBFile dbFile)

Deletes the specified database file. The caller should ensure that the database file is closed and is going to be unused.

Parameters:

dbFile - the database file to delete

Throws:

FileSystemException - if the file cannot be deleted for some reason