CSCI 111 LAB 3

Worth:10 points

The three main tasks of this lab are to become familiar with the java API, with make files, and writing your first simple program. Presently in the java JDK provided by Sun, there are over a thousand different classes described in the API that we can use to build our programs. Plus there are thousands of classes being created by companies and individuals for our use as well everyday. With so many classes it would extremely hard to know them all and all their features, hence we rely on written documentation to lookup features of each class. The API or "Application Programming Interface" provides the base level information on the use of java and the provided classes.

Using your favorite browser visit the following URL and look up the Applet class, Color class and the Graphics class. The Applet class is in the java.applet package and the others are in the java.awt package.
```
       http://java.sun.com/javase/6/docs/api/overview-summary.html 
```
In a file that you name APIinspect, write down the names of each of these classes along with two "methods" from each (so that it is easy to see which methods come from which class). Include a brief description of each of the methods you chose for each class. Complete the rest of the assignment and include a tag that references this file in your web page submission of this lab (as you did with the README in Lab 2).
Make sure you are in the public_html/csci111/lab3 directory before you start these commands. We want to store our java and html files for lab 3 in the proper directory (i.e., in lab3). If you have not already set up a lab3 subdirectory, go back to lab 1 and set up your directories.
If you cannot see things, permissions might not be correct OR you might not have made the index.html files discussed in lab 1. If the problem is permissions, see the man pages and below for an explanation of chmod arguments
Move (remember...cd) into the lab3 directory before issuing the following commands. We are going to copy 4 files into the public_html/csci111/lab3 directory.
```
           cp  ~amk/courses/csci15a/15a_examples/makefile   ./
           cp  ~amk/courses/csci15a/15a_examples/Lab3.java   ./
           cp  ~amk/courses/csci15a/15a_examples/example.html   ./
           cp  ~amk/courses/csci15a/15a_examples/example.java   ./
```
These four files will be used to complete the assignment. There is a special file called a "makefile", this is used by the Unix "make" utility to build applications. The makefile provides a way to organize the process of compiling multiple files. Take an example of a program with 20 source files, you would only need to issue one command to compile the whole program rather than multiple compile (javac) commands to rebuild the program. More importantly the "make" utility only rebuilds the files where changes have been made. Examine the makefile by typing the following command. Note that the commands for compiling are included in the file.
```
    cat makefile
```
To compile the Lab3.java source file you need only type the following command.
```
    make
```
If there were errors they would have been written to the error.log file.
You should fix these errors and call make again until there are no more errors (this is like editing and recompiling).
Once the program is running smoothly and you are happy with it, you should make documentation. To create an API for your program, type the following command which will use the javadoc utility to create a group of .html files. But don't do it yet. Read the next indented paragraph first.
```
    make docs
```
This tells the makefile to run the DOC command. The DOC command that is in this particular makefile creates a new directory called _docs where it puts all of the documentation files created.
From now on, always supply a link to both your source code and your .html API javadoc generated code on all of your lab submissions. Note that the href for the docs should point to the proper directory and file, ie. _docs/Lab3.html or _docs/package-summary.html
The example.html file that you copied is an html file that can be used as a template for basic general submissions. Look at it. By default, the API generated code for a .java class will have the same name as the class (in this case Lab3) with the extension .html. To be able to link to all of the related classes in the package, the javadoc produced package-summary.html is what one links to.

In the future you will be writing makefiles and it would be a good idea to read up on "make" using the "man" command. I also have some more notes on makefiles.
Drawing in java is accomplished using the Graphics class. What you may find confusing is the coordinate system used to do the drawing. All coordinate points are represented by positive integer values only. Zero, Zero (0,0) is the top left corner of the drawing area ( right now the applet surface ). One of the reasons the coordinate system is confusing is that Y values get greater as you move down instead of the usual negative that has been drilled into us from math class.
```
  0----> positive x direction
0
 |
 |
 |
 \/
positive y direction
```
Modify the basic Lab3.java Applet to display a simple drawing of something recognizable using at least four different methods from the Graphics class and at least three different colors. If you have trouble getting started look over the example.java source code for ideas. Also in the class notes are examples with code. (Some examples: java indeed, music and playing it, art (the frame is done using the Graphics class), food, water, and time (precisely). Oh, and more class , weather )
You may need to fix things.
AHHH! A nice suggestion is to draw what you want using the Paint tool (Programs|Accessories|Paint in Windows) ( KolourPaint for Linux or Unix? another link). A nice feature of that free tool is that it tells you what pixel your cursor is on at the bottom of the frame. This might help with the java commands. Thanks to Joshua Diel for this helpful hint.
For students interested in polygons or fonts
Submission:
- On Campus Go to your Vista page for this course, and to the Assignments link.
  Go to the Lab Assignments: drop box link and then to lab 3 and follow directions for submission.
- Distance/Web students Submit your lab by going to http://www.ecst.csuchico.edu/~amk/foo/csci111/turnin/
Web Page Submission Required Contents:
1. a link to the results from exercise number 1 (APIinspect),
2. a link to the javadocs .html generated in number 2 (e.g., _docs/Lab3.html),
3. a link to the source (with paint method using at least four different methods from the Graphics class and at least three different colors), and
4. the link to the url of the lab 3 applet (recognizable drawing) so that I can take a look at it
  (or the applet can be running on the submission page (e.g., lab3.html) with all of the above links).
All can be put on one web page that looks very much like the one you copied over (example.html). Make sure that all files that you link to on this page are what you think they are. I will not go hunting for your applet, you will not get credit if I can not get to your applet from the url you provide for the lab.

Advice

To save the errors generated when we compile a java source file, we can have those errors written to a file instead of to the screen. That way we can look over the errors and if there are many errors, we won't miss the first few after they have scrolled off the screen. Here is an example of how to do this....

   javac filename.java 2> error.log

If there are errors, they will be written into the file error.log which we can examine with the Unix commands "cat", "more" or "pico"...or you can look at the file using WINSCP.

This error.log file is automatically made if you use the make command discussed above.

Web Sites of Interest

http://www.kaffe.org/
http://www.alphaWorks.ibm.com/Home/
http://www.hungry.com/
http://www.classpath.org/
http://www.gnu.org/
http://www.mozilla.org/
http://www.sfgate.com/sf/zippy/
chmod Change Mode
Files can be accessible by the user owner (u) (easy to remember ... it is you), groups (g) and other users (o).
Hence the ugo (using ugo is actually equivalent to a (for all))
Permissions for a file can be seen by doing
```
 
        ls -l filename   (for specific file)
        ls -ld filename  (for specific directory)
        ls -l            (shows all files and subdirs in current dir)
```
You see something like:
```
        -rw-r--r--
```
The first - is to indicate if it is a directory (it will have a d rather than a - if it is a directory rather than a file)
The next three --- are for file owner, the middle three are for group and the last three for others.
The three --- stand for read (r), write (w), and execute (x).
A - indicates the permission is not given.
Remember, for your directory, you were told to do
```
         chmod ugo+rx lab3 
```
thus giving the user, group and others read and execute permission. Directories need to have execute permissions in order for people to get into them ... and read permissions in order to be able to see the files in them.
Sometimes you see people use numbers instead. They represent the binary representation of each of the three ---. For example -rw-r--r-- is 644 since read has a value of 4, write has a value of 2 and execute has a value of 1. (Consider possible values and placement in a binary number.) Thus rw- is 4+2 or 6 and r-- is 4. Thus 644. So a command equivalent to the one you did for setting lab3 would be
```
         chmod 555 lab3
```
for read (4) and execute (1) permissions for all three settings.
Important: you need to make sure you give yourself write permission for you own files or you cannot edit them