CS 226: Data Structures, Program #3 (Project 1)

Turtle Recall

Assigned: Monday, September 27, 2004
Due: Monday, October 4, 2004, 11:59 pm (GRADED!!)

(Reminder: Please do not look at each other's source code except for any designated project partner. We will be actively looking for programs that are "too similar", and I do not wish to find any.)

Overview

This program is the third component of the Turtle Commander project. Your submission will be graded as Project 1. In this program, you will give some "memory" to your TurtleCommander in the form of stack and queue data structures. These various memories make it possible to implement the push, pop, undo, and redo turtle commands, adding greater flexibility to the overall turtle graphics package.

Command Descriptions

For this assignment, you will be implementing push, pop, undo, and redo.

push

The push command pushes a copy of the current TurtleState onto a stack data structure. This is a mechanism for remembering the turtle's current location, orientation, color, pen state, and autodisplay state.

pop

The pop command replaces the current TurtleState with the one on top of the state stack. So, for example, if you want to draw something with a branching structure, you might reach the branch point, apply a push command, traverse the first branch, apply a pop command (returning the turtle to the branch point), and finally traverse the second branch.

undo

The undo command removes the effects of the most recent turtle command (excluding undo and redo).

redo

The redo command re-applies a previously undone turtle command (excluding undo and redo). Note that issuing new turtle commands besides undo and redo should invalidate any currently redoable commands.

Classes

TurtleStateStack

You should write a class that implements the following interface:
public interface TurtleStateStack {
    public int size();
    public boolean isEmpty();
    public TurtleState top() throws StackEmptyException;
    public void push(TurtleState element);
    public TurtleState pop() throws StackEmptyException;
}
To show that you understand the adapter pattern described in class and your textbook, you should first implement a stack class that deals with elements of the generic Object class, then incorporate this generic implementation into your specialized implementation. You may use the LinkedStack implementation in your textbook for the generic stack.

This class will allow you to implement the push and pop turtle commands.

TurtleCommandQueue

You should write a class that implements the following interface:
public interface TurtleCommandQueue {
    public int size();
    public boolean isEmpty();
    public TurtleCommand front() throws QueueEmptyException;
    public void enqueue (TurtleCommand element);
    public TurtleCommand dequeue() throws QueueEmptyException;
}
As in the TurtleStateStack, you should first implement a generic Object queue (you can use one from the textbook), then employ the adapter pattern to use it to implement the above interface.

Using the TurtleCommandQueue, you can implement the undo turtle command. Enqueue all your TurtleCommands onto the queue (except undo/redo), then use the stored commands to regenerate the entire drawing  (except the last command) when an undo is called. Note that we do not want to see all the individual commands being redrawn to accomplish a single undo, even if autodisplay is enabled. Note also that in theory, you could use this TurtleCommandQueue to reissue all the drawing commands on every call to paint( ), but this would be much slower than maintaining the offscreen buffer you developed for Program 2. So you should only re-issue all the drawing commands when an undo is called.

TurtleCommandStack

You should write a class that implements the following interface:
public interface TurtleCommandStack {
    public int size();
    public boolean isEmpty();
    public TurtleCommand top() throws StackEmptyException;
    public void push(TurtleCommand element);
    public TurtleCommand pop() throws StackEmptyException;
}
You can use the same generic stack implementation from the TurtleStateStack, but use the adapter pattern again to specialize it to this modified interface. The TurtleCommandStack will allow you to implement the redo command. Commands which are undone using the undo command should be pushed onto your TurtleCommandStack. If a redo command is issued, a command may be popped off the TurtleCommandStack, and reissued.

You must take some care to keep the undo queue and the redo stack consistent with each other. For example, suppose you issue the commands:
move 20
undo
move 10
redo
The call to "move 10" should actually invalidate or clear your redo stack, so the redo should have no effect (and could result in some error condition for you to handle). This is a semantic aspect of the typical undo/redo interface in most application programs.

Create Some Cool Drawings

Once you have implemented the command set, start making some drawings!  Be sure to test the command set thoroughly. Remember, in addition to interactively typing commands, you can redirect the commands from a test file (as described in Program #1). Unfortunately, it will currently be too difficult to combine the two in a single execution of your program. But you can experiment interactively with the program, then type all the commands you want to keep into a text file. You can repeat commands nicely in that framework using cut and paste, etc. Submit some of your test cases in text files, and note in the README what each one shows. Also submit one or more of your most creative drawings as text command sets (don't include captured image files, which could take lots of storage space).

I have posted a new sample command file and the correspondingsample image using this extended turtle command set for you to play around with. Note that by combining undo/redo with control of the autodisplay state and manual display commands, you can even create animations of sorts.

Restrictions

You may use the java.io, java.lang, java.awt, and javax.swing class libraries. In general, you may not use classes from the java.util library unless you receive permission to do so for some particular class. Standard exceptions to this rule are StringTokenizer and the Random (which may be useful for testing some of your programs and does not jeopardize the goals of the class).

Submission - Read  this Carefully

Your submission should include a set of .java files, a README.txt file with any information you want to tell the grader about running your program (even though this one is ungraded), and some text files with your best test cases and pictures. If you are working with a designated project partner, you should specify the submission ids of the team members (you only need to submit the program under a single person's submission id). Your main program class should be called TurtleCommander, and it should be compilable using "javac TurtleCommander.java" and runnable with the command "java TurtleCommander". You should submit your program as a single .zip (zip archive) file. This file should have no directory structure in it -- just the actual files, so extracting them should result in all your original files placed in the current directory.

To submit, you should follow these steps:
  1. Create the .zip file for submission
  2. Make a new, empty directory
  3. Copy the submission file to the new directory
  4. Extract all the files from your submission file into the new directory
  5. Verify that you can compile and run the program on your test cases in the new directory
  6. Go to the submissions page
  7. Submit the .zip file, making sure that the file appears in the directory listing displayed in the browser after submission (the file size listed could be slightly different on the recipient SunOS machine from that of a Windows  OS machine, but they should be very similar)
  8. Also in the submissions page, View the submission to be certain that the file is there (you should see basically the same directory listing you saw at the end of step 7).
If anything goes wrong with steps 7 or 8, try repeating them (resubmitting your file overwrites any previous submission and time stamp). If you cannot successfully submit your assignment, immediately send e-mail to the professor and the head TA explaining the problem (with all details so we can hopefully fix it) and including the submission file as an e-mail (MIME) attachment. It is your responsibility to verify that the assignment is received. If we do not have an assignment or record of its submission, it will receive zero points.

Grading

Your Project 1 will be graded according to the criteria such as:
Compiling and running
Proper execution on a number of our test cases (with valid and invalid inputs)
Overall implementation correctness
Comments, style, and readability (informative,  but not extraneous comments are appreciated)
Effort/creativity of created pictures
If a project does not compile, you can expect to receive very few points, if any. This should encourage you to take care in your submission process.

Final Words of Encouragement

This is it, the real, graded assignment! Good luck, and have fun! With this complete command set at your disposal, you will have the power to create some really neat pictures. So try it out, and send us a few (some of the best ones will be posted on the web site). Remember, if you have problems understanding the assignment or how to carry it out, please contact the TA, CA, or me. We want to help all of you succeed, and are available by e-mail as well as office hours and appointments (if none of the office hours work for you).
Home
September 27, 2004