Nicholas Duchon at UMUC

Submitting Java Projects

Turning in a Project  

Documentation - Still required
*.java - source code files - Still required
Relevant data files - Still required
Directories - OLD
*.class - compiled class files - OLD
javadoc - OLD
HTMLConverter - REALLY OLD
chmod -R a+rx - UNIX and OLD

Explanation of documentation and coding requirements for Java projects (2014):

Files
Project Grading
Criterion description





readme
file
doc,
txt,
or
html
Design Include a description of:
  • problem statement
  • your approach
  • classes
  • methods
  • variables
  • algorithms
  • any useful diagrams
  • classes should generally include a toString() method
User's Guide How exactly would a person use your program, including exactly how to start it.
Test Plan and Results
Include:
  • A detailed and reproducible set of test data,
  • EXPECTED outputs, and
  • actual outputs
Lessons Learned Anything special you learned in doing this project.
"I did not learn anything." is a very bad lesson learned!



Java
source
code
files
Correctness and Elegance This category includes:
  • indentation
  • good design
  • elegant solution
  • good selection of classes and methods
  • good use of library classes
  • any reports explaining results
  • comments in the code,
    • commenting all right brackets
    • header comments in each file
    • citations
    • useful comments in the code
  • javadoc output (optional)
 

Java Environment -  javaPlaces
My Comments
Some External Links
JDK - Java Development Kit  Java Developer Connection
 Documentation & Training
 SDK Development Tools
J2EE - Java 2 Enterprise Edition  Java(TM) 2 Platform, Standard Edition
javadoc   Javadoc Tool Home Page
Applets Netscape 
Internet Explorer 
Java(TM) Plug-in Product
appletviewer
Applications -
HTMLConverter   Java Plug-in Software HTML Converter Download
UNIX Commands   UMUC Information Technology: UNIX Guide
 Creating a Web Page
Permissions -
Editors vi 
pico 
emacs 
Wordpad
dos2unix -
Java coding conventions   Code Conventions for Java Programming Language
Java IDE's (Integrated Development Environments) jGRASP Home Page
JBuilder
Visual J++
VisualAge Micro Edition
Visual Cafe WebGain
 CodeWarrior for Java    Metrow
 Forte Application Environment
  JavaWorld Developer Tools Guide: IDE

JDK -  Java(TM) 2 Platform, Standard Edition

The Java Development Kit has been the primary source of the state of the art in the Java language since Sun Microsystems, Inc., introduced the Java language in the early 90's. The kit includes a number of executable images (javac, java, javadoc, jar, appletviewer, jdb, and others), demos, some documentation, the standard java classes and a variety of other stuff. A short description of some of the most important images follows:

J2EE - Java(TM) 2 Platform, Enterprise Edition - Overview

Java 2 Enterprise Edition "adds full support for Enterprise JavaBeansTM components, Java Servlets API, JavaServer PagesTM and XML technology." These topics are rather beyond those covered in the first three CMSC courses (130, 230 and 335), but for those who are interested, check out the following web page:
 

javadoc -  Javadoc Tool Home Page

Produces really nice documentation quickly. I strongly recommend you using this tool.
I recommend using the following command:
> javadoc -author *.java
This will produce a set of html files, starting with "index.html", and a file for every class in the folder, with the name "<class-name>.html". Because of this naming convention, you should not create your own "index.html" in this folder, and you should not have any html files with your class names. There are a few other files generated, which you should also avoid - you can view the results by doing a javadoc and checking the results.

The reason to avoid files that javadoc produces is that one can then run "javac *.java" and "javadoc *.java" on any platform and get good results. You should call your documentation file something like "readme.html" and the file needed to run your applet something like "run.html", to stay out of the way of javadoc. ALSO - some systems (particularly Microsoft operating systems) are generally not case sensitive about file names while UNIX systems generally are. The problem is when MS packages change the capitalization of file names and then send the changed names to UNIX - or vice-versa.

Applets

Applets are created when the primary class of an applications extends Applet or JApplet, and the program is started using a web page (say run.html).

The standard methods used in applets are: "init", "start", and "paint". Two other methods are available, "stop" and "destroy", but the calls to them tend to be unpredictable and you are generally discouraged from using them.

The file "run.html" needs to create a drawing canvas and put the applet into the canvas. A simple html file is shown below:

<html><body>
<applet code=MyClass.class width=500 height=500>
</applet>
</body></html>
The code argument should be the name of the applet class you wish to execute, in this case in the same folder as the html file. It is important to specify some reasonable "width" and "height" parameters, otherwise the applet may start but the user will not be able to see anything.

The user would start this applet either by using the "appletviewer run.html" command, or by viewing this web page with a browser, such as Microsoft Internet Explorer or Netscape. The browser must have access to a version of the Java run-time library that has all of the library classes used by the applet - see notes about the HTML Converter below.

Note that a class that extends Applet or JApplet may actually have a main program that instantiates the applet directly, in which case the program would be started as an application. See the following code for such an example (note the existence of a "main" method of the source code):
http://nova.umuc.edu/~duchon/CIRCUITS/v6/Circuits.java .

Applications

Java applications are identified by the existence of a method, "public static void main (String args[])". The variable "args" is arbitrary, but the rest of the line must be typed as written. If this is a method in a class, say "MyClass", then the program can be invoked by the command "java MyClass", which will result in the Java run-time environment eventually calling the "main" method in "MyClass". Note that the call starting the program does not use the full file name: "java MyClass.class" will fail with a rather strange error message!

Applications may create windows and may be graphically oriented, but no application or applet you create can "run on" nova.umuc.edu, since students only have a text-based interface to that computer (telnet). So the only way to see a graphic program hosted on nova is to make the program an applet with a web page calling it, see the Applet section above.

HTMLConverter -  Java(TM) Plug-in 1.3 Documentation

If your application uses only classes that are available in the default jre (Java run-time environment) available in the browser you and all of your clients are using, you do not need to concern yourself with this converter. In particular, Netscape 6.2 uses Java 1.3.1 by default.

UNIX Commands -  Information Technology FAQs - UMUC

The following are some of the more important UNIX commands (you should look at the "man" page for each command for more information):

man, chmod, mkdir, cd, ls, dir, (lpr?), rm, cat, .cshrc, which, more/less, mv, cp, dos2unix, unix2dos, tee, rmdir, ps

Permissions -  UMUC Information Technology: Creating a Web Page

The simplest approach is the go to the "www" directory and issue the command "chmod -R a+rx *". Make sure that your student account has execute permission and the www directory has read and execute permissions.

Editors

MS-DOS uses the "editor" command.

UNIX has the following editors available: "pico", "emacs", and "vi"

The integrated development environments (see below) have built-in editors.

dos2unix

This command takes the line breaks used on MS-DOS text files (CR + LF) and converts them to (LF), which is the UNIX text file standard. Without this conversion, UNIX editors generally have a very hard time editing the files. The output of this command is "standard out", which means that you should redirect the output to a file. Example:
> dos2unix MyClass.java > newfile.java
> rm MyClass.java
> mv newfile.java MyClass.java

Java coding conventions -  Code Conventions for the Java(TM) Programming Language: Contents

Java has a variety of coding conventions, but the most common are the naming conventions: Indentation is similar to C++. Basically, groups of statements that are part of the same block should be indented at the same level, indicating that they are related. I STRONGLY suggest (require in my classes) that all right brackets "}" be commented, indicating the block that the programmer thinks is being closed - note that the compiler may not necessarily agree, which is a programming error. See the documentation from Sun for their complete

IDE's 

A variety of integrated development environments are avaible for Java programmers, some or which are: These environments generally require the programmer to start by creating a project, then including Java and other files which make up the project. This can be very convenient once the environment is created. Typically, these environments will also include significant debugging help and good connections between the compiler and the source code, indicating any errors. One must be careful about using library classes and methods that are environment specific because such code may not be portable.


Projects:

You should look at my "ideal" programming project. I used the word ideal in this context to indicate that this example covers the basic elements of a project, not that it is perfect!

All of your files, except the compiled ".class" files, should include your name, the file name, the date, the class, what version of the JDK is required, applet and/or application, and the problem you are solving.

Directories

Your projects should be turned put in a subdirectory of your class www account, typically something like /class/cs330a/29/www. Under that account, you should create a separate directory for each of your projects labelled as instructed in the syllabus for you particular class, section and semester.

readme.html

READY? You must start this file with a statement saying either "This project is ready." or "This project is NOT ready.", otherwise I will have no idea whether your project is done or is still being developed.

The readme.html file should contain sections describing the design, user's guide, test plan, lessons learned and any other notes you think are needed to explain what your project does and how it works.

Source code

All of the source code for your project should be present in the correct directory, linked to the index.html file generated by javadoc for your project, and readable over the net. The source code should include relevant comments and explanations. It is important that you format your code and following some recognized programming conventions. Indentation and comments are particularly important, and I emphasize the idea of commenting every } (right bracket). Comments should be helpful, not just filler or distracting. As in any language, names should follow conventions, be descriptive and be reasonable.

Class bytecode

All of the code of your project should be compiled and ready to run the project directory. Except for projects that require access to files, which must be run as applications, it would be nice if all of your projects could run as applets and be ready to run over the net. If your project uses the JDK/JRE 1.1 version, a simple html page will do, but if you use the classes in JDK/JRE 1.2 or higher, you should use the HTMLConverter utility. Actually, I have downloaded Netscape 6.2, which seems to include the JRE 1.2 (or higher), so as far as I am concerned, the HTML converter is not necessary.