The README.TXT File

You must create a single text file (in plain ASCII format; word processor formats are unacceptable) called README.TXT and place it in the root directory of your project. Make sure you include the following information:

• The exact SDK version you used, including the platform you worked on. You can get this information by using the java -version command.

• Explain how to run the programs. You must provide exact command-line instructions. If any environmental setup is required, be sure to include instructions on how to perform the setup. For example, do not say something like "Add server.jar to your classpath." You should document exactly how to add the JAR file to the classpath . Also, perhaps you will require scripts to set up the environment and run the application. If you do use scripts, be sure your instructions tell the evaluator how to run the application using these scripts. Note that your program must run correctly, no matter what directory it is installed in.

• The location of your database file (for example, database.bin). It should be in the install directory, not a subdirectory.

• The location of your design choices document.

• The names of the files you have submitted, a note specifying their location in the directory structure, and a short description of each one's purpose.

Each project's README.TXT file will differ . However, they should all follow the order given in the preceding list. Some people put too much information in this file. One common mistake is to confuse this file with the design choices document. Don't explain how or why you did things here. Also, don't bother explaining any problems you had with configuration issues.

Make sure the README.TXT file is in the root directory, not in a subdirectory. This is such a simple instruction that if you don't follow it, the evaluator will get a bad impression from the start.

The following example shows the complete contents of a README.TXT file. Can someone quickly run your application by reading the first few lines? This file should be especially concise and the sections arranged in the correct order.

README FILE

SUPER BOWL README FILE

Candidate : Firstname Lastname

Date : March 10, 2004

TABLE OF CONTENTS

1. Quick Start

2. Introduction

3. SDK Version and Platform

4. Execution Instructions

5. Location of Data File

6. Design Choices Document

7. File Listing

8. User Documentation Web Page

1 Quick Start

1.1 Local Mode:

 java myPackage.client.SuperBowlClient -dbpath database.bin 

1.2 Remote Mode:

JVM #1 :

 java myPackage.server.DatabaseRMIServer -host localhost -port 1234 -dbpath database.bin 

JVM #2 :

 java myPackage.client.SuperBowlClient -host localhost -port 1234 

2 Introduction

Thank you for your efforts toward grading this submission. This submission used the Java 2 SDK development environment for building the Super Bowl Reservation application, and components were written in the Java programming language (Java 2 SDK, Standard Edition Version 1.4.1) to be deployed on the Java platform.

The RMI portion of this submission allows the user to access the database remotely. RMI was chosen for its maturity over plain sockets, as is evidenced by the fact that RMI is built on sockets. The RMI parts do not provide a graphical user interface.

3 SDK Version and Platform

The SDK version used for this project was 1.4. The following is detailed information on the exact Java version:

 java version "1.4.1" Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1-b21) Java HotSpot(TM) Client VM (build 1.4.1-b21, mixed mode) 

This project was developed and tested using Windows 2000. The following details the exact operating system information:

 Microsoft Windows 2000 5.00.2195 Service Pack 2 

This project was developed and tested on a Dell laptop. The following details the exact hardware information:

 Dell Inspiron 8000 Laptop Pentium III 900MHz 15 inch UXGA screen 256MB SDRAM 32MB DDR 4xAGP NVIDIA GeForce 2 Go 20GB HD 

4 Execution Instructions

There are two ways to run the Super Bowl Reservation application: in standalone mode and in networked mode. In either mode, please change the current working directory to the install directory before executing commands. After successfully starting the client, you should see a GUI with buttons on the left and a table in the middle.

4.1 Standalone Mode

In standalone mode, you need to start only one JVM to run the client application.

4.1.1 Start the Server in Local Mode

The server is not used in local mode.

4.1.2 Start the Client in Local Mode

Change the directory to the install directory and run the following command:

 java myPackage.client.SuperBowlClient -dbpath database.bin 

or

 java myPackage.client.SuperBowlClient -dbpath $ROOT\database.bin 

Where:

 $ROOT=install directory The path separator is "\" for Windows, but "/" for Unix. 

4.2 Network Mode

In network mode, you need to start the server in one JVM and the client in another JVM.

4.2.1 Start the Server with No Parameters

To start the server without parameters, run the following command:

 java myPackage.server.DatabaseRMIServer 

If you start the server without parameters, the following conditions are assumed:

 HOST=localhost PORT=1099 DBPATH=$ROOT\database.bin $ROOT=install directory 

4.2.2 Start the Server with Parameters

You can start the server with parameters. The parameter pairs can be in any order, but all three pairs are required, like so:

 -host {HOST} -port {PORT} -dbpath {DBPATH} 

For example:

 java myPackage.server.DatabaseRMIServer -host localhost -port 1234 -dbpath database.bin 

After successfully starting the server, you should see a confirmation message.

4.2.3 Start the Client with Parameters

After the server has been started, you can start the client in network mode. This requires two parameter pairs. The pairs can be in any order, but both pairs are required. Notice that the parameter pairs used to start the client must match exactly the parameter pairs used to start the server, like so:

 -host {HOST} -port {PORT} 

For example:

 java myPackage.client.SuperBowlClient -host localhost -port 1234 

5 Location of Data File

The data file, database.bin, used for this assignment is located under the install directory. You can specify the location of the database.bin file, assuming it is in the installed location, with the following statement:

 -dbpath database.bin 

Or you can provide the entire path, like so (using "\" for Windows, or "/" for Unix):

 -dbpath $ROOT\database.bin 

6 Design Choices Document

The design choices document is located in the install directory under the name DESIGN_DECISIONS.TXT.

7 File Listing

The following list outlines the contents of the Super Bowl Reservation application directory, as well as the purpose of each directory or file:

 Install_Directory     README.TXT                  This document     DESIGN_DECISIONS.TXT        The major design decisions     database.bin                The database file     instructions.html           The instructions     userHelp.html               Help file for the GUI     + myPackage                 Contains all the object class files       +- client                 All the client class files         SuperBowlClient         The application GUI       +- server                 All the server (RMI) class files         DatabaseRemote          Database decorator for remote operation         DatabaseRemoteServer    Registers object for remote mode       +- database               All the database related classes         Database                Provides database services         DatabaseException       General exception object for application         DatabaseFactory         Generates local or remote database         DatabaseInterface       Methods for local-remote modes         LockManager             Insert Row Locking     + source                    Contains all the Java source files       +- client                 All the client source files       +- server                 All the server (RMI) source files       +- database               All the database source files     + javadoc                   Directory for documentation       +- index.html             javadoc start 

8 User Documentation Web Pages

The user documentation can be viewed from the client menu under HELP or directly at Install_Directory/userHelp.html.