Stock Interface & ExceptionsHomepage  « Case Study « Stock Interface & Exceptions

In this section of the case study we look at the model code for our project and code as much of the model as we can from the information provided. The stakeholder Stocking Goods Limited have supplied us with an interface that must be implemented and from this we can also derive some exception classes. The exception classes we need to code to honour the contract of the Stock interface are DuplicateKeyException, RecordNotFoundException and SecurityException. So to get a clean compile on the the Stock Interface we will need to code up these exceptions first. All the exception classes are similar and allow us to throw an exception alone, with a message or chained and all of these classes extend the RuntimeException class. All the exception classes can be thrown remotely and so are serialized and use a version number so that serialisation can occur without worrying about the underlying class changing between serialization and deserialization.

We also decided in the Proposal Conclusions that a situation might arise where a user tries to stock goods that have already been stocked by another user and if this happens we will need to throw a StockingException and so we will also create and compile this class.

Compiling The DuplicateKeyException Classgo to top of page Top

The following DuplicateKeyException class will be be thrown when we try to create a record that already exists.

Cut and paste the following code into your text editor and save it in the   c:\_Case_Study\src\model directory.


package model;

/**
 * Holds any duplicate key exceptions that may occur in the StockImpl class.
 * 
 * @author Kevin 
 * @version 1.0
 * @see StockImpl
 *
 */
public class DuplicateKeyException extends RuntimeException {

    /**
     * A version number for the DuplicateKeyException class so that serialisation 
     * can occur without worrying about the underlying class changing 
     * between serialisation and deserialisation.
     * 
     */
    private static final long serialVersionUID = 871964L;

    /**
     * Create a default DuplicateKeyException instance.
     * 
     */
    public DuplicateKeyException() {
        super();
    }

    /**
     * Create a DuplicateKeyException instance that accepts a String.
     * 
     * @param e The string description of the exception.
     */
    public DuplicateKeyException(String e) {
        super(e);
    }

    /**
     * Create a DuplicateKeyException instance and chain an exception.
     * 
     * @param e The exception to wrap
     */
    public DuplicateKeyException(Throwable e) {
        super(e);
    }
}

Compiling Our Source File With the -d Option

Open your command line editor:

Change to directory  cd c:\_Case_Study\src\model

Compile DuplicateKeyException.java using the java compiler with the -d option
  javac -d ..\..\classes DuplicateKeyException.java

Because we have used a package (package model;) at the top of the code the compiler has created this directory within the classes directory. When we look in the model directory we can see the compiled DuplicateKeyException.class file.

compile DuplicateKeyException

Compiling The RecordNotFoundException Classgo to top of page Top

The following RecordNotFoundException class will be be thrown when we try to create a record that is not found which can occur when we try to read, update, delete or lock a record.

Cut and paste the following code into your text editor and save it in the   c:\_Case_Study\src\model directory.


package model;

/**
 * Holds any record not found exceptions that may occur in the StockImpl class.
 * 
 * @author Kevin 
 * @version 1.0
 * @see StockImpl
 *
 */
public class RecordNotFoundException extends RuntimeException {

    /**
     * A version number for the RecordNotFoundException class so that serialisation 
     * can occur without worrying about the underlying class changing 
     * between serialisation and deserialisation.
     * 
     */
    private static final long serialVersionUID = 871964L;

    /**
     * Create a default DuplicateKeyException instance.
     * 
     */
    public RecordNotFoundException() {
        super();
    }

    /**
     * Create a RecordNotFoundException instance that accepts a String.
     * 
     * @param e The string description of the exception.
     */
    public RecordNotFoundException(String e) {
        super(e);
    }

    /**
     * Create a RecordNotFoundException instance and chain an exception.
     * 
     * @param e The exception to wrap
     */
    public RecordNotFoundException(Throwable e) {
        super(e);
    }
}

Compiling Our Source File With the -d Option

Open your command line editor:

Change to directory  cd c:\_Case_Study\src\model

Compile RecordNotFoundException.java using the java compiler with the -d option
  javac -d ..\..\classes RecordNotFoundException.java

Compiling The SecurityException Classgo to top of page Top

The following SecurityException class will be be thrown when we have a lock record mismatch which can occur when we try to update, delete or unlock a record.

Cut and paste the following code into your text editor and save it in the   c:\_Case_Study\src\model directory.


package model;

/**
 * Holds any security exceptions that may occur in the StockImpl class.
 * 
 * @author Kevin 
 * @version 1.0
 * @see StockImpl
 *
 */
public class SecurityException extends RuntimeException {

    /**
     * A version number for the SecurityException class so that serialisation 
     * can occur without worrying about the underlying class changing 
     * between serialisation and deserialisation.
     * 
     */
    private static final long serialVersionUID = 871964L;

    /**
     * Create a default SecurityException instance.
     * 
     */
    public SecurityException() {
        super();
    }

    /**
     * Create a SecurityException instance that accepts a String.
     * 
     * @param e The string description of the exception.
     */
    public SecurityException(String e) {
        super(e);
    }

    /**
     * Create a SecurityException instance and chain an exception.
     * 
     * @param e The exception to wrap
     */
    public SecurityException(Throwable e) {
        super(e);
    }
}

Compiling Our Source File With the -d Option

Open your command line editor:

Change to directory  cd c:\_Case_Study\src\model

Compile SecurityException.java using the java compiler with the -d option
  javac -d ..\..\classes SecurityException.java

Compiling The StockingException Classgo to top of page Top

The following StockingException class will be be thrown when a user tries to stock goods that have already been stocked by another user.

Cut and paste the following code into your text editor and save it in the   c:\_Case_Study\src\model directory.


package model;

/**
 * Holds any stocking exceptions that may occur in the StockImpl class.
 * 
 * @author Kevin 
 * @version 1.0
 * @see StockImpl
 *
 */
public class StockingException extends Exception {
    /**
     * A version number for the StockingException class so that serialisation 
     * can occur without worrying about the underlying class changing 
     * between serialisation and deserialisation.
     * 
     */
    private static final long serialVersionUID = 871964L;

    /**
     * Create a default StockingException instance.
     * 
     */
	public StockingException() {
		super();
	}

    /**
     * Create a StockingException instance that accepts a String.
     * 
     * @param e The string description of the exception.
     */
	public StockingException(String e) {
		super(e);
	}

    /**
     * Create a StockingException instance and chain an exception.
     * 
     * @param e The exception to wrap
     */
	public StockingException(Throwable e) {
		super(e);
	}
}

Compiling Our Source File With the -d Option

Open your command line editor:

Change to directory  cd c:\_Case_Study\src\model

Compile StockingException.java using the java compiler with the -d option
  javac -d ..\..\classes StockingException.java

Compiling The Stock Interfacego to top of page Top

The following Stock interface will be used in other projects and so must be implemented as is. The interface provides the contract for the CRUD operations for the Manufacturer file as well as templates for the search and locking/unlocking mechanisms.

Stocking Goods Limited have also included doc comments for the interface which are written in HTML and can be turned into a document at a later date using the Javadoc tool. Stocking Goods Limited have also requested that we provide doc comments for all class, field, constructor and method declarations.

Cut and paste the following code into your text editor and save it in the   c:\_Case_Study\src\model directory.


package model;

/**
 * An interface implemented by classes that provide use of the Manufacturer file.
 * 
 */
public interface Stock {
	
	/**
	 * Creates a new record in the Manufacturer file which could be a deleted
	 * entry. Inserts the given Manufacturer data, and returns the record
	 * number of the new record.
	 * 
	 * @param manufacturerData An array of Manufacturer data fields.
	 * 
	 * @return The record number of the Manufacturer record created.
	 * @throws DuplicateKeyException Record already exists.
	 */
	public long createRecord(String[] manufacturerData) throws DuplicateKeyException;
	
	/**
	 * Reads a record from the Manufacturer file and returns a String
	 * array where each element is a Manufacturer field value.
	 * 
	 * @param recNo A record number denoting the byte location in the 
	 * Stock file where this Manufacturer record starts.
	 * 
	 * @return A String array containing the fields of the 
	 * Manufacturer record.
	 * 
	 * @throws RecordNotFoundException Indicates the record was not found.
	 */
	public String[] readRecord(long recNo) throws RecordNotFoundException;
	
	/**
	 * Modifies the fields of a Manufacturer record. The new value for field n 
	 * appears in manufacturerData[n]. Throws a SecurityException if the record 
	 * is locked with a number other than lockRecord.
	 * 
	 * @param recNo The record number of the product record to read.
	 * @param manufacturerData A String array of Manufacturer fields.
	 * @param lockRecord The lock value.
	 * 
	 * @throws RecordNotFoundException Indicates the record was not found.
	 * @throws SecurityException Indicates a lock record mismatch.
	 */
	public void updateRecord(long recNo, String[] manufacturerData, long lockRecord)
			throws RecordNotFoundException, SecurityException;
	
	/**
	 * Deletes a record, making the record number and associated disk storage
	 * available for reuse. Throws SecurityException if the record is locked
	 * with a number other than lockRecord.
	 * 
	 * @param recNo The record number of the product record to read.
	 * @param lockRecord The lock value.
	 * 
	 * @throws RecordNotFoundException Indicates the record was not found.
	 * @throws SecurityException Indicates a lock record mismatch.
	 */
	public void deleteRecord(long recNo, long lockRecord)
			throws RecordNotFoundException, SecurityException;

	/** 
	 * Returns an array of record numbers that match the specified search. Field n 
	 * in the Manufacturer file is described by searchCriteria[n]. A null value in 
	 * searchCriteria[n] matches any field value. A non-null value in 
	 * searchCriteria[n] matches any field value that begins with searchCriteria[n]. 
	 *
	 * @param searchCriteria The search criteria for retrieving records.
	 * 
	 * @return A long array of manufacturer record numbers
	 * matching the search criteria.
	 */
	public long[] findBySearchCriteria(String[] searchCriteria);

	/**
	 * Locks a record so that it can only be updated or deleted by this client.
	 * Returned value is a number that must be used when the record is unlocked,
	 * updated, or deleted. If the specified record is already locked by a
	 * different client, the current thread goes into a wait state until the 
	 * record is unlocked.
	 * 
	 * @param recNo The record number of the Manufacturer record to lock.
	 * 
	 * @return The record number of the locked Manufacturer record.
	 * @throws RecordNotFoundException Indicates the record was not found.
	 */
	public long lockRecord(long recNo) throws RecordNotFoundException;

	/** Releases the lock on a record. Lock number must be the same as the number
	 * returned when the record was locked; otherwise throws SecurityException.
	 * 
	 * @param recNo The record number of the Manufacturer record to unlock.
	 * 
	 * @throws SecurityException Indicates a lock record mismatch.
	 */
	public void unlock(long recNo, long lockRecord) throws SecurityException;
}

Compiling Our Source File With the -d Option

Open your command line editor:

Change to directory  cd c:\_Case_Study\src\model

Compile Stock.java using the java compiler with the -d option
  javac -d ..\..\classes Stock.java

compile Stock interface

As you can see from the screenshot we get a compiler error because the compiler can't find the exception classes we just compiled. This is because we are now putting our compiled classes into separate folders from our source using the -d option. To find them we need to use another compiler option to point to the directories the class files reside in.

Compiling Our Source File With the -classpath Option

When compiling our source files we have the option of pointing the compiler to directories where other compiled classes are, that we need to cleanly compile the class in question. There are two options available to do this, these being -classpath and the abbreviated version -cp. In this example we will use -classpath and for future compiles we will use -cp.

Open your command line editor:

Change to directory  cd c:\_Case_Study\src\model

compile Stock.java using the java compiler with the -classpath and -d options
  javac -classpath ..\..\classes -d ..\..\classes Stock.java

The following screenshot shows that we now get a clean compile and also the classes now compiled into the classes\model directory.

compile Stock interface 2

Related Java6 Tutorials

Flow Control - Handling Exceptions
Flow Control - Declaring Exceptions
Flow Control - Creating Our Own Exceptions
Swing - RMI - Serialization
OO Concepts - Interfaces


What's Next?

In the next section we set up the Model elements of the MVC pattern.

<<  Model Part 1 Overview                    Manufacturer OO Request  >>

go to home page Homepage go to home page Top