ScenarioJ8 Home « Scenario

• <<    J8 Home
• Setup     >>

In the first lesson of the case study we look at a project proposal for a Java based project. We start by looking at information gathered from the stake holder who we shall call 'Stocking Goods Limited' and how this can be translated into a multi tiered user application fit for purpose.

Project Proposal Top

Stocking Goods Limited are a wholesaler of general goods that are stocked from various locations around the country. Each day they stock the goods required to fulfill orders from customers invoices. Currently this is achieved by several clerks who tally up invoices and call the various manufacturers who stock the goods required.

As the company has grown and the number of invoices and stock to order has increased, the manual user processes are becoming more error prone and Stocking Goods Limited want a new user system to automate invoice calculation and stock purchasing. They have decided that the invoice calculation processes are more involved and can be deferred to the second phase of automation. For the initial phase of the project they want the stock purchasing side of the business automated.

Information forwarded by Stocking Goods Limited includes the file structure of the Manufacturer data file whose format musn't be changed and an interface that must be implemented without amendments. The reasoning behind this is that another project group are working in tandem on a reporting system and Stocking Goods Limited have provided both projects with the format of a Manufacturer data file and a Stock interface that must be implemented as is.

The project will be written using Java technology only and must implement the following features:

• A client application that uses a GUI written in Swing which connects to the Manufacturer data file and can be run in networked or non-networked mode. This will be achieved using the following command line arguments appended to our startup application:
  1. "client" - Run the application in non-networked mode so that access to the Manufacturer data file from the GUI runs in the same JVM and doesn't include any networking or serialization of objects.
  2. "" (no argument) - Run the application in networked mode so that access to the Manufacturer data file from the GUI runs in a different JVM and includes networking and serialization of objects.
• Network server functionality that allows access to the Manufacturer data file remotely using RMI-JRMP. This will be achieved using the following command line argument appended to our startup application:
  1. "server" - Run the application in server mode with functionality that provides the logic for displaying configurable objects and starting and exiting the server in a safe manner.
• Access to the Manufacturer data file must include search, stocking and unstocking functionality and provide record locking for the Manufacturer data file as specified in the Stock interface.
  • Search functionality should include the capability to search by name, by location, by name and location or search all records.
  • Stocking orders should only occur once. If the amount entered is wrong the goods will have to be unstocked and the correct stock order reentered.
  • Stocking Goods Limited do not anticipate more than one program having concurrent access to the Manufacturer data file as the reporting system will be run in batch overnight. So our locking only needs to deal with multiple concurrent clients using the server.
• The code needs to be self documenting and the javadoc tool will be run on project completion to produce system documentation.
  • We write doc comments in HTML and these must precede a class, field, constructor or method declaration. Doc comments are made up of a description followed by block tags which are the names of parameters, return types, pointers etc. (@param, @return, and @see are examples of block tags).

Manufacturer File Format Top

Stocking Goods Limited have provided us with the format of the Manufacturer data file they want us to use although there is no test file provided. We will have to create a Manufacturer test file ourselves which we do in Create Manufacturer Test File in the next lesson.

Stocking Goods Limited have requested that we create a class representing the record information within the Manufacturer file called unsuprisingly Manufacturer as they see a lot of future reuse of this file and it will also be helpful when implementing the Stock interface.

A Manufacturer object should be a representation of the Manufacturer file record information in an object oriented framework, allowing easy access to fields.

Stock Interface 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. As requested by the stakeholder, we will have to also provide doc comments for all class, field, constructor and method declarations.

/**
 * 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.
     * @param lockRecord The locking number.
     * 
     * @throws SecurityException Indicates a lock record mismatch.
     */
    public void unlock(long recNo, long lockRecord) throws SecurityException;
}

Proposal Conclusions Top

After reading through the information supplied to us by Stocking Goods Limited we can draw certain conclusions:

1. We will be using a package called model to store the supplied Stock interface in.
2. We will need to implement the Stock interface and shall call the implementation class StockImpl.
3. We will need to create some exception classes in the model package, to honour the contract of the Stock interface, these being DuplicateKeyException, RecordNotFoundException and SecurityException.
   • A situation might also 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 an exception which we will call StockingException.
4. The Manufacturer file, Stocking Goods Limited have asked us to create, will also go in the model package.
5. We will also be creating a new GUI and will be accessing services locally and also remotely using RMI-JRMP. This scenario fits in well with the MVC pattern and so we will use this pattern for the project.
6. As we are using the MVC pattern we will place all our GUI (view) code into a client package.
7. As we are using RMI-JRMP and will have local and remote services we can place our controller code into services and RemoteServices packages.
8. If we are running in "server" mode we will need to include a Swing panel to automate information gathering for the remote location of the Manufacturer file used as well as a port number. We can then use this information to create and register a remote connection using RMI-JRMP for our remote clients to connect to.
9. We will need to seamlessly connect local or remote clients and therefore will have to include Swing panels to automate information gathering for the location of the Manufacturer file used as well as a port number if we are running remotely. If fact the file information is common to all three run modes so we can use the same Swing panel and include a port number where appropraite.
10. Stocking Goods Limited hava requested functionality to search, stock and unstock the Manufacturer file and these services must be available to local and remote clients.

Lesson 1 Complete

That's it for the Scenario lesson in which we read a project proposal and made some conclusions from it.

Related Java Tutorials

Fundamentals - Primitive Variables
Objects & Classes - Class Structure and Syntax
Objects & Classes - Methods
OO Concepts - Interfaces
Exceptions - Declaring Exceptions
API Contents - Inheritance - Using the package keyword
Swing - Gui Concepts
Swing - RMI

What's Next?

In the next lesson we setup up some directories for the project and create a Manufacturer test file.

• <<    J8 Home
• Setup     >>