CSCI 1321 (Principles of Algorithm Design II), Spring 2003:
Homework 1

Due:

Design due January 29, 2003, at 5pm; code due January 31, 2003, at 5pm.

Credit:

Design 40 points; code 20 points.

What you are to do

Review Dr. Lewis's Project Description. Then read the specific instructions for Assignment 1.

Creating a project using Together

See the course links page for information on running Together on one of the lab machines or on your own machine. Once you have started Together, do the following to create a new project and set it up for this assignment.

• In the File menu, select New Project to create a project. You will be prompted to choose a name for the project and a folder (directory) for its location. If you are doing this under Linux on one of the lab machines, this folder should be somewhere in your home directory. (Notice that the top-level file-selection menu should have a choice ``Home'' that takes you to your home directory.) You probably should not put the code and its documentation in the same directory. A reasonable approach would be to create a directory PAD2 (or CS1321, or whatever appeals to you) in your home directory and then make a subdirectory for each assignment.

• Download Dr. Lewis's JAR file (containing the code he is supplying for this assignment) from his Assignment 1 page; put it in the same directory/folder as the project you just created.

• Add the JAR file to the project's classpath, so that the classes you write will be able to use the classes in the JAR file: In the Project menu, select Project Properties. Select the Search/Classpath tab, click Add Path, Library, or Archive, and select the JAR file you just downloaded. Notice that the classes in the JAR file will not show up in your project's diagram. On the whole this is probably a good thing. Caution: If you mistakenly add the JAR file to the Project Paths tab, the classes inside will show up in your project's diagram, but the Java runtime will not be able to find them. If this happens, remove the JAR file from the Project Paths tab and add it to the Search/Classpath tab. One would think there would be a way to have the JAR file appear on both tabs, but this appears not to work.

• Create a ``main'' class for your game using the Designer panel or by starting with the File menu and selecting first New and then Class. Right-click on the UML diagram for the new class and select Properties. This should bring up the class's properties in the Inspector panel. The Properties tab shows the class's name, among other things. Change it to something meaningful for your game.

Completing the design step

Once you have your project set up as described above, do the following steps to finish the design part of this assignment.

• Add comments to your main class describing your game: Bring up your main class's properties in the Inspector panel as described earlier (right-click on the class's UML diagram and then choose Properties). Select the Description tab. Type your description of the game in the Description panel that comes up.

• Generate HTML documentation for your project: In the Project menu, select Documentation, then Generate HTML. You will prompted for the location of the folder (directory) in which to put the generated documentation. If you put the documentation in a subdirectory of your Local/HTML-Documents directory on Sol, it will be viewable from the Web. (For example, the contents of user jsmith's directory Local/HTML-Documents/Thing can be viewed using URL http://www.cs.trinity.edu/~jsmith/Thing.) Please follow the naming conventions outlined in Dr. Lewis's project description. For the design step of assignment, this means putting the files generated by Together in directory Local/HTML-Documents/PAD2Project/Assn1/Design. Be sure your files can be read by others. You should be able to check this by pointing a browser to URL http://www.cs.trinity.edu/~yourusername/PAD2Project/Assn1/Design and confirming that all the links work. If you get error messages about access being forbidden, cd to the directory containing your documentation and use the following Unix command to set the permissions properly.

  chmod -R go=rX .

  The dot at the end is part of the command. If after executing this command you still get ``access forbidden'' messages, the problem may be with permissions on the Local or Local/HTML-Documents directories; cd to your home directory and type the following two commands.

  chmod go+x Local
  chmod go+x Local/HTML-Documents

Turning in your design

Send me e-mail (at bmassing@cs.trinity.edu) telling me that your design is ready to be graded. Please use a subject line that mentions the course name and the assignment number (e.g., ``cs1321 design 1'' or ``PAD2 design 1''). You are free to make changes to your work after sending this message, but be advised that if the files containing your documentation have timestamps past the deadline, the assignment will be considered late.

Completing the code step

For this step, you are to add a main() method to your main game class. The parameters, return type, etc. of this method should be the same as in the examples we will be doing in class. What the body of the code should do is described in Dr. Lewis's Assignment 1 writeup. You will be making use of his GameSetup and MainFrame classes; to find out how to use these classes, read his project documentation.

Once you have written your code, compile it and test it. Here are some tips on writing, compiling, and testing your code using Together. They assume that you have followed the preceding steps for creating a project and documentation for your main class.

• To add code (a main() method) to your main class, you can open it in the Editor panel (by double-clicking on its class diagram in the Designer panel) and type the code in directly. (There are other ways of creating code with Together, but this is probably the simplest at this point.) When you have it typed it, save it (by starting with the File menu and selecting Save). You can actually change things in your class using the Editor panel, the Inspector panel, and the Designer panel. Changes you make in one panel show up in the other one(s) when you save them.

• Try compiling your code: In the Project menu, select Make Project. (Or find the Make Project icon on the toolbar.) You will see any error messages in the Message Pane panel at the bottom.

• Once you get code that compiles without errors, try running it: In the Run menu, select Run. (Or find the Run icon on the toolbar.) This pops up a window with more prompts. Choose the Application tab and fill in the box labeled Select class for 'main' with the name of your main class.

• If you have done everything right, you will now get a little window that allows you to play a very simple game (solid black screen, player that moves around in response to the arrow keys). You will probably want to make the window bigger, and to make the player move you may need to hold the arrow keys down longer than you might think. If you don't get such a window, the Message Pane panel should contain error messages indicating what went wrong.

When you are happy with how your code works, generate a final version of your documentation, as described above except putting the result in Local/HTML-Documents/PAD2Project/Assn1/Final.

Turning in your code

E-mail the source code for your main class to me at bmassing@cs.trinity.edu, again using a subject line that mentions the course name and the assignment number (e.g., ``cs1321 code 1'' or ``PAD2 code 1''). This code will be in a file with the extension .java. (For example, if your main class is called MyGame, this file will be MyGame.java.) The simplest way to do this is probably to use your favorite mail program and attach the .java file as an attachment. I do not recommend cutting and pasting source code into a mail program; this tends to result in garbled code.

Hints and tips

Notice that you can do everything except generate HTML documentation using command-line tools, if you need to work on your project on a computer that doesn't have Together installed or doesn't have enough memory to run it with acceptable performance (or if you just decide you prefer editing code with vim!). See Java Without an IDE for details. If you do this, the next time you open the project with Together, it should pick up any changes you made with other tools; you can use the Synchronize with External Changes option from the File menu if it doesn't seem to be doing so.