Nicholas Duchon at UMUC
Submitting Java Projects
|Design||Include a description of:
|User's Guide||How exactly would a person use your program, including exactly how to start it.|
| Test Plan and Results
|Lessons Learned||Anything special you learned in doing this
"I did not learn anything." is a very bad lesson learned!
|Correctness and Elegance||This category includes:
|JDK - Java Development Kit|| Java Developer
Documentation & Training
SDK Development Tools
|J2EE - Java 2 Enterprise Edition||Java(TM) 2 Platform, Standard Edition|
|javadoc||Javadoc Tool Home Page|
Java(TM) Plug-in Product
|HTMLConverter||Java Plug-in Software HTML Converter Download|
UMUC Information Technology: UNIX Guide
Creating a Web Page
|Java coding conventions||Code Conventions for Java Programming Language|
|Java IDE's (Integrated Development Environments)||jGRASP
VisualAge Micro Edition
Visual Cafe WebGain
CodeWarrior for Java Metrow
Forte Application Environment
JavaWorld Developer Tools Guide: IDE
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:
- javac - the Java byte-code compiler, takes source code (*.java) and turns it into Java bytecode (*.class).
- java - executes a Java class, starting as the "public static void main (String st)" method.
- javadoc - automatically generates beautiful html documentation, use "javadoc -author *.java" for simple projects.
- jar - put a bunch of bytecode class files (*.class) into a single file, useful for quicker net response - the whole project goes at once.
- appletviewer - start an applet in a simple viewer, may be able to read and write files (my experience with this is mixed), will not run over the net.
- jdb - the Java debugger. I usually prefer just putting print statements in my code.
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:
Produces really nice documentation quickly. I strongly recommend you using this tool.
I recommend using the following command:> javadoc -author *.javaThis 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 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>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.
<applet code=MyClass.class width=500 height=500>
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):
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.
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.
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
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.
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.
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 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
- Class names should start with a capital letter, then the rest should be lower case with every new word again starting with a capital. There should be no spaces or special characters. Thus: "MyGreatCatClass".
- Instance, class and parameter variables and method names should start with a lower case letter, then capitalize the first letter of every word as class names. Thus: "myFirstVariableName", "thisIsAGreatMethod".
- Final variables should be all caps. Thus: "RED", "PI", "THISISAFINALVARIABLE".
A variety of integrated development environments are avaible for Java programmers, some or which are:
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.
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.
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.
- Design - a description of approach you used to solve the problem, what classes, variables, methods, etc., you chose to use, and, if relevant, a description of how they fit together with each other and the runtime environment. You should also describe how your project fits into the Java environment. For those of you in the more advanced classes, something similar to UML would be a good start. the javadoc tool does a lot of this work for you, in one sense, so your discussion should focus on why you made these choices (classes, instance variables, methods, etc.), not just a list of the choices you made.
- User's Guide - How does a user find your project, start it, what should be input, and what output should be expected.
- Test Plan - this section should be along the lines of "type this input", then "expect this output", and perhaps a third column of "this is what happens".
- Lessons Learned - anything that did not work as you expected before you started the project. I expect something more than statements such as "I learned how to use the compiler".
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.
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.