DBMain.java

package suncertify.db;

/**
 * An interface implemented by classes that allow access to the
 * bookings database.
 *
 * @author Sun Microsystems
 * @version 1.0
 */
public interface DBMain {

    /**
     * Reads a record from the database. Returns an array where each
     * element is a record value.
     *
     * @param recNo The record number to read from the database.
     * @return A String[] object containing the booking data
     * @throws RecordNotFoundException Indicates the requested recNo does not
     * exist or has been deleted.
     */
    public String[] read(int recNo) throws RecordNotFoundException;

    /**
     * Modifies the fields of a booking record. The new value for field
     * <b>n</b> appears in <b>data[n]</b>.
     * 
     * @param recNo The record number to update.
     * @param data A String[] object containing the new values for the booking.
     * @throws RecordNotFoundException Indicates the record to be updated does
     * not exist or has been deleted.
     */
    public void update(int recNo, String[] data)
            throws RecordNotFoundException;

    /**
     * Deletes a record, making the record number and associated disk storage
     * available for reuse.
     *
     * @param recNo The record number to delete.
     * @throws RecordNotFoundException Indicates the record to be deleted does
     * not exist or has already been deleted.
     */
    public void delete(int recNo) throws RecordNotFoundException;

    /**
     * Query the database to find specific bookings.
     *
     * @param criteria An array of criteria. Field <b>n</b> in the database is
     * described by <b>criteria[n]</b>.
     * A <b>null</b> value in <b>criteria[n]</b> matches any field value.
     * A non-<b>null</b> value in <b>criteria[n]</b> matches any field value
     * that begins with the <b>criteria[n]</b>.
     * (For example: "Fred" matches "Fred" or "Freddy".)
     * @return an array of record numbers that match the given criteria.
     * @throws RecordNotFoundException WHY?!
     * TODO: Why does find throw a RecordNotFoundException?
     */
    public int[] find(String[] criteria)
            throws RecordNotFoundException;

    /**
     * Creates a new booking record. Inserts the given data and returns the
     * record number of the new record.
     *
     * This may overwrite a previously deleted record, given the same record
     * number.
     *
     * @param data An array containing the booking data to be created.
     * @return the record number for the newly created booking record.
     * @throws DuplicateKeyException Indicates that the record number
     * specified in <b>data</b> is already in use.
     */
    public int create(String[] data) throws DuplicateKeyException;

    /**
     * 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.
     *
     * @param recNo The record number to lock.
     * @throws RecordNotFoundException Indicates the given record number does
     * not exist or has been deleted.
     */
    public void lock(int recNo) throws RecordNotFoundException;

    /**
     * Releases the lock on a record.
     *
     * @param recNo The record number to unlock.
     * @throws RecordNotFoundException Indicates the given record number does
     * not exist or has been deleted.
     */
    public void unlock(int recNo) throws RecordNotFoundException;

    /**
     * Indicates if a record is currently locked.
     *
     * @param recNo The record number to check for a lock.
     * @return true if the record is locked, false it's not.
     * @throws RecordNotFoundException if the specified record number does
     * not exist or has been deleted.
     */
    public boolean isLocked(int recNo)
            throws RecordNotFoundException;
}

RecordNotFoundException.java

package suncertify.db;

/**
 * Throw RecordNotFoundException when the requested database record
 * is not available.
 * 
 * @author Ariejan de Vroom
 * @version 1.0
 */
public class RecordNotFoundException extends Exception {

}