Category list

Javadoc Comments

Javadoc is the Sun Microsystems tool (http://java.sun.com/j2se/javadoc) for generating application programming interface (API) documentation in HTML format from document comments in source code. In the code, you use special comment characters ”starting with /** and ending with */ ”to indicate that the javadoc tool should process the comment to produce HTML-formatted documentation.

Writing javadoc comments can become an entire project in itself, and you need to be thorough because Sun does review code comments. There are several approaches to javadoc commenting. You do not have to worry about it, however. Just be sure to add comments that are enclosed in the multiline comment for every major declaration. The text is written in HTML and must precede a class, field, constructor, or method declaration. These comments are structured as a description followed by special javadoc tags, such as @param , @return , and @see .

Javadoc comments are part of your grade, so don't be shy about commenting your code. Every class and method should be commented in such a way that the javadoc tool can grab it. To see how to do this please refer to Sun's guidelines on writing javadoc comments in code at http://java.sun.com/j2se/javadoc/writingdoccomments/index.html. For detailed reference material on Javadoc tags please refer to http://java.sun.com/j2se/javadoc/index.html#javadocdocuments. The following is an example of how to comment a method that results in proper javadoc documentation:

/**
 * Returns a Blob object that represents a customer.
 * The id argument must specify a single customer. The last_name
 * argument is a description that will be displayed later.
 * <p>
 * This method will either return a Blob or a null if the
 * Blob doesn't exist.
 *
 * @param  id        the customer unique identifier
 *         last_name the customer's last name
 * @return      the customer Blob
 * @see         Blob
 */
 public Blob getBlob(int id, String last_name)
 {
    try
    {
            Blob blob = getCustomer(id);
            if(blob != null)
            {
                    blob.setLastName(last_name);
                    return blob;
            }
    } catch (NoBlobException e)
    {
        return null;
    }
 }

You can also check your comments with a tool at Sun called DocCheck. It will give you a report describing style and tag errors in your source code. The home page is http://java.sun.com/j2se/javadoc/doccheck/index.html.

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

Quick Start
Introduction
SDK Version and Platform
Execution Instructions
Location of Data File
Design Choices Document
File Listing
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

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