suncertify.db
Class Data

java.lang.Object
  |
  +--suncertify.db.Data
All Implemented Interfaces:
DBMain

public class Data
extends java.lang.Object
implements DBMain

Data class is a simple implementation of database access class. Implementation is based on RandomAccessFile class. It does not cover the most significat problems of file access eg.:

- reallive implementation should consider the problem of inconsistent data file - effective alghoritms for searching like indexing
- effective alghoritms for inserting data (pointer to the first free entry)
- data caching should be consider

All above problems were consider not crucial for thie solution of SUN assignement and the following solution was proposed: - implmentation works on the one copy of db file - and system crash during writting may destory its consistenty - implemntation does not use indexes for speedup

Locking - general concept while implmenting the lock machnism was to put all lock information in the map indexed by the record id. This makes finding lock information for the specified record quite simple. Another approach was to keep in the map the information about the client locking the row - the clientId string. The problem was that we may not do wait on this objects as it use to change - if more then two clients wait for the unlock the whole idea has to be refine. To overcome the problem the supported class was created - LockObject. This class know the current id of the client owning the row and has one object (that does not chage when client id changes) to wait on for all the clients.


Field Summary
static int MAGIC_COOKIE
          The value of magic cookie that maut be at the begginig of a data file
 
Constructor Summary
Data()
          Creates new instance of Data class using default filename as DBfile
Data(java.lang.String fileName)
          Creates new instance of Data class using the specified fielName as DBfile
 
Method Summary
 void closeDB()
          The method closes the db file - created for secure server shutdown you should never use the Data object after calling this method!!
 int create(java.lang.String[] data)
          Creates a new record in the database (possibly reusing a deleted entry).
 void delete(int recNo)
          Deletes a record, making the record number and associated disk storage available for reuse.
 int[] find(java.lang.String[] criteria)
          Returns an array of record numbers that match the specified criteria.
 boolean isLocked(int recNo)
          Determines if a record is currenly locked.
 void lock(int recNo)
          Locks a record so that it can only be updated or deleted by this client.
 java.lang.String[] read(int recNo)
          Reads a record from the file.
 void unlock(int recNo)
          Releases the lock on a record.
 void update(int recNo, java.lang.String[] data)
          Modifies the fields of a record.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAGIC_COOKIE

public static final int MAGIC_COOKIE
The value of magic cookie that maut be at the begginig of a data file

See Also:
Constant Field Values
Constructor Detail

Data

public Data()
     throws IncorrectDataFile,
            java.io.IOException
Creates new instance of Data class using default filename as DBfile

Throws:
java.io.IOException - - is thrown if file does not exist or cannot be opened
IncorrectDataFile - - is thrown when magic cookie value is incorrect
See Also:
PropertiesWrapper.getDbFileName(), MAGIC_COOKIE

Data

public Data(java.lang.String fileName)
     throws java.io.IOException,
            IncorrectDataFile
Creates new instance of Data class using the specified fielName as DBfile

Parameters:
fileName - - the name of the file with data to be opened
Throws:
java.io.IOException - - is thrown if file does not exist or cannot be opened
IncorrectDataFile - - is thrown when magic cookie value is incorrect
See Also:
MAGIC_COOKIE
Method Detail

read

public java.lang.String[] read(int recNo)
                        throws RecordNotFoundException
Reads a record from the file. Returns an array where each element is a record value.

Specified by:
read in interface DBMain
Parameters:
recNo - the index of the requested record
Returns:
string array with the values of requested record fields
Throws:
RecordNotFoundException - is thrown if a specified record does not exist or is marked as deleted in the database file.
See Also:
DBMain.read(int)

update

public void update(int recNo,
                   java.lang.String[] data)
            throws RecordNotFoundException
Modifies the fields of a record. The new value for field n appears in data[n].

Specified by:
update in interface DBMain
Parameters:
recNo - the index of the record to operate on
data - the new set of data for the requested record
Throws:
RecordNotFoundException - is thrown if a specified record does not exist or is marked as deleted in the database file.
See Also:
# update(int, java.lang.String[])

delete

public void delete(int recNo)
            throws RecordNotFoundException
Deletes a record, making the record number and associated disk storage available for reuse. First it locks the desired record - may hung uppon it is avaliable then it make requested changes (modify the delete flag) and releses the lock

Specified by:
delete in interface DBMain
Parameters:
recNo - the index of the record to delete
Throws:
RecordNotFoundException - is thrown if a specified record does not exist or is marked as deleted in the database file.
See Also:
lock(int), DBMain.delete(int)

find

public int[] find(java.lang.String[] criteria)
           throws RecordNotFoundException
Returns an array of record numbers that match the specified criteria. Field n in the database file is described by criteria[n]. A null value in criteria[n] matches any field value. A non-null value in criteria[n] matches any field value that begins with criteria[n]. (For example, "Fred" matches "Fred" or "Freddy".)

Specified by:
find in interface DBMain
Parameters:
criteria - String array representing the criteria for each record field
Returns:
array containig indexes of all records meeting the criteria
Throws:
RecordNotFoundException - is thrown if a specified record does not exist or is marked as deleted in the database file.
See Also:
DBMain.find(java.lang.String[])

create

public int create(java.lang.String[] data)
           throws DuplicateKeyException
Creates a new record in the database (possibly reusing a deleted entry). Inserts the given data, and returns the record number of the new record.

Specified by:
create in interface DBMain
Parameters:
data - the array string representig values of the fields of the new record
Returns:
index of the newly created record
DuplicateKeyException
See Also:
DBMain.create(java.lang.String[])

lock

public void lock(int recNo)
          throws RecordNotFoundException
Locks a record so that it can only be updated or deleted by this client. If the specified record is already locked, the current thread gives up the CPU and consumes no CPU cycles until the record is unlocked.

If a row is already locked by the current thread nothing happen - if we make thread owing the lock waiting for unlock it would wait forever.

Specified by:
lock in interface DBMain
Parameters:
recNo - the index of the record to lock
Throws:
RecordNotFoundException - is thrown if a specified record does not exist or is marked as deleted in the database file.
See Also:
DBMain.lock(int)

unlock

public void unlock(int recNo)
            throws RecordNotFoundException
Releases the lock on a record. The method tries to relese the lock of the specified record. It succeed only when row was locked by the caller else (in case the row is not locked or is locked by somebody else) no action is performed.

Specified by:
unlock in interface DBMain
Parameters:
recNo - the index of the record to unlock
Throws:
RecordNotFoundException - is thrown if a specified record does not exist or is marked as deleted in the database file.
See Also:
DBMain.unlock(int)

isLocked

public boolean isLocked(int recNo)
                 throws RecordNotFoundException
Determines if a record is currenly locked. Returns true if the record is locked, false otherwise.

Specified by:
isLocked in interface DBMain
Parameters:
recNo - the index of the record to check
Throws:
RecordNotFoundException - is thrown if a specified record does not exist or is marked as deleted in the database file or in case of problem with file access.
See Also:
DBMain.isLocked(int)

closeDB

public void closeDB()
The method closes the db file - created for secure server shutdown you should never use the Data object after calling this method!!