In this assignment you will write a graphics-based program to draw a "rectangular" spiral, centered in the window. This is based on Programming project 6.21 in our textbook.
This assignment will give you practice creating and implementing classes, using loops and conditionals, doing console-based IO, drawing to a graphics window, and writing a unit test. Also you'll get practice with the program development process. Please read over the whole assignment before beginning: in particular, do not wait until the assignment is due to read about submitting it: you'll want to do your first submit before the final deadline, because when you submit it we do some checks on your code, and you will be able to resubmit if you fail those checks (but not if you are out of time).
This document may seem voluminous, because it includes some instructional material, and hints on how to do certain things. You'll need to read it or parts thereof more than once, possibly skimming some parts on the first reading. To help you find things as you are working on the assignment, here is a table of contents for the main sections:
In the normal Vocareum configuration, you have a Linux terminal, but no way to run a program with a graphical user interface (GUI). For this assignment we are using a different Vocareum configuration that will allow you to open multiple windows, including a separate one to run your GUI program. With this configuration, when you start up Vocareum for this assignment, it will allow you to open up a virtual Linux desktop in your browser. Note: You will not be able to run GUI programs from the regular Linux terminal that appears under the source code area of the regular Vocareum IDE.
How to start up a virtual Linux Desktop in Vocareum
The way you get to a virtual linux desktop in this assignment is to go
to a menu that's on the upper right of the workbench window: choose
Actions--> Applications --> Desktop.
That will open a linux desktop in another tab in your browser. If it starts with a pop-up dialog, choose "Use default configuration." There are a few ways to open a terminal window in this desktop. You can use the Applications menu at the top left of the screen, and choose "Terminal Emulator". Or you can right click anywhere on the desktop, and choose "Open Terminal Here".
Warning: depending on how you started up the terminal, it might not start out in your home directory (i.e., "work"), but rather starts in the root directory ("/") or somewhere else. So the first thing you should do is
cdto get into your home directory. (One way to check if you are in your home directory is you will see the ~ (tilde) right before the $ in the Linux shell prompt.)
Your home directory will be populated with the starter files we are providing you. Part of what we provided is source code for a complete sample Java GUI program there, so you can try out compiling and running such a program in this environment before you write code for your own program. Compile and run this program:
javac CarViewer.java java CarViewerMore about this car example (from Section 3.8 of the textbook) later.
You can switch between these two tabs in your browser to switch between editing (normal Vocareum window), and compiling and running (Linux desktop). To make it easier to see your compile errors at the same time as you view your source code, you can put the Vocareum tab in a different browser window altogether.
Another option with the desktop is to use one of the other source code editors available within the desktop itself. I saw emacs and vim (Rt-click on desktop-->Applications-->Accessories). I'm not sure how fast these work on this platform, so if you end up using one of these, let me know how it goes. (I only opened emacs there briefly once; it started up pretty fast, so that's a good sign.) Both emacs and vim are a little different than other editors you are used to, so you probably would want to take a look at an online tutorial on the web before using them. Eclipse is also available there; it may be somewhat slower than running it locally.
You can disconnect from the Desktop by closing its tab, or from the main Vocareum window (upper right) do: Actions-->Applications-->Stop App. Then you can restart later the same way you did the first time.
Using another IDE for this assignment
If you don't want to use Vocareum and its Linux desktop as your
development environment, you can use another IDE running locally on
your own machine.
If you choose go this other route, you would do the following:
The files in bold below are ones you create and/or modify and submit. The ones not in bold are files you will use, but that you should not modify. The ones with a * to the left are starter files we provided.
"I certify that the work submitted for this assignment does not violate USC's student conduct code. In particular, the work is my own, not a collaboration, and does not involve code created by other people or AI software, except for the resources explicitly mentioned in the CS 455 Course Syllabus. And I did not share my solution or parts of it with other students in the course."
Then it will display a 500 tall by 800 wide pixel window with the spiral displayed on it, such that the start of the first segment is centered in the window.
Here is a screenshot of output from one run of our solution to this assignment, where our responses to the console prompts were to use a 10-pixel initial segment length, and draw a 30-segment spiral (shown in the (500, 800 window)).
Here's a different spiral to make it easier to see how each segment is arranged (initial segment = 20, number of segments = 10). Also, I resized window before doing this screenshot of the window, so that's why the window is smaller.
If some of the segments to be displayed based on the input values given would go outside the window, that part of the spiral will not be visible: this is the expected behavior. For example, here's a spiral with initial segment length of 10, and number of segments = 100, shown without resizing the window:
As mentioned in the textbook, every time a window gets resized or iconified and de-iconified paintComponent gets called again. Here's a later screenshot created during the same run shown above, but after the user dragged the corner to make the window larger, and now the whole spiral is visible. Note that the spiral is centered in the new window dimensions.
Similarly if the user makes the window smaller while running the program, a completely visible spiral could become partially hidden after the resize.
More about the graphics library methods necessary to get these results in the section on Graphics programming.
There are a few other requirements for the assignment discussed in the following sections. To summarize here, the other requirements are:
Enter length of initial segment: -5 ERROR: value must be > 0 Enter length of initial segment: -1 ERROR: value must be > 0 Enter length of initial segment: 0 ERROR: value must be > 0 Enter length of initial segment: 5Your program does not have to handle non-numeric input. (We will not test it on that case.)
We are giving you the exact interface to use for this class. By interface, we mean what clients need to know about the class to use it, i.e., the class name, the class comment, the public method headers and associated method comments. Do not change the public interface when you incorporate it into your own program. We have provided skeleton code for SpiralGenerator.java. Please read the class and method comments in that file for its exact specification.
Note: For all work in this course, when we say do not change the interface for a class, we mean no changing the class name or the provided method headers, no adding public methods, no removing public methods. As part of the grading process, we will be using our own test programs with such classes, and if you change the public interface your code might not even compile with our test programs. We will be testing whether your class implementation matches the specification.
SpiralGenerator does not depend on any of the other classes you are creating here. It does depend on the Java library classes Point and Line2D, see the section on lines and points for more about these classes.
The Car example
Our program
follows the conventions of graphical classes used in the textbook (see
Resources, near the beginning of this
document, for relevant textbook readings). In particular, the design
for this assignment overall follows the car example from Section 3.8 of the
textbook that has a viewer and a component. One difference is the
car example also has a graphical object that can get instantiated
multiple times and drawn in different locations on the screen (the
Car class). We have no such analogous class in our design.
You will do all the drawing in the SpiralComponent class
itself.
We provided you with the source code for that example as part of the starter files for this assignment. You can use the code in CarViewer.java as a starting point for your SpiralViewer class for this assignment.
In addition to examining the general structure of the car example code, you can use it to test out running a GUI program in the Vocareum virtual Linux Desktop before developing your own code. When you run it there, you can also see how the display changes when you change the size of the window in which the CarViewer application is running and the corresponding code that gets that to happen (the display for your program will also change when the window is resized).
We also modified CarComponent.java a little bit from the version of the code from the text: we instrumented the code so it prints a message to the console every time paintComponent gets called, to help you better understand when the Java Swing graphics framework calls paintComponent. To see this, once you start running the program, make sure you can see the terminal window, as well as the CarComponent window; then try resizing the CarComponent window, and minimizing it and opening it again.
Any program of non-trivial size will be developed faster, with fewer bugs, using the technique of incremental development, which means developing and testing pieces of the program incrementally. The incremental aspect is that your program may gradually grow until it includes the complete functionality. (Other people use different names for the same thing. Sometimes it's called building subsets.)
A desirable feature of individual classes is that they are as independent as possible from a program that uses them. Some classes, such as String, or ArrayList (which we will see soon) are general-purpose and can be used in many different programs. Other classes are more special-purpose, such as SpiralGenerator, but still are modules that can be separated from a particular program that uses them. We can test such a module using a unit-test, which is a program specially designed to test the module.
We often unit-test one (or more) classes, and then once we are convinced that unit is working correctly, we can integrate that class with other code that uses it. If this larger code base is now buggy, we can feel fairly certain that the bug is in the new code we added, since we already tested the first class. So any time we find bugs, it's in a small program: much easier than locating bugs in large programs.
Similarly, if we make later changes or enhancements to our application our code will be more robust in the face of these changes because, in our unit-test, we tested the module in ways not specific to how it was used in this application. (As you have experienced as a user, software is always getting changed over time, e.g., the latest version of Windows is in the double-digits.) For example, in our SpiralViewer we would not be able to see if SpiralGenerator had the correct results for spirals that start using negative coordinates.
For this assignment, the final product will not be a very large program, but we want to get you in the practice of using incremental development, so you will still be successful when you are trying to develop and debug much larger programs. Even in this program there are at least two distinct issues to deal with: (1) figuring out how to create the correct sequence of segments (2) figuring out how to do a graphics-based program in Java. It will be much easier you we can deal with these issues one at a time, so you can isolate bugs related to each one more easily. For this assignment you are required to write a console-based Tester class to test your SpiralGenerator class. This test program is described in more detail in the next section.
As mentioned in the previous section a test program like SpiralGeneratorTester is called a unit test; we have discussed such unit tests in lecture, and they are also discussed in Section 3.4 of the textbook. One goal of this test program is for you to test the functionality of the SpiralGenerator class.
How to compile and run multi-file Java programs on the command line Often you can just list the file that contains main in the compile command and javac figures out what other classes are used in that program and compiles those as well. However, sometimes the Java compiler gets confused when you only have modified some of the source files since the original compile. For running a program that uses multiple class files, the only class name you give as the argument to the java virtual machine is the one containing main.When you are compiling and running your test program you should be able to do it as follows:
javac SpiralGenerator*.java java SpiralGeneratorTesterThe wild-card ("*" symbol) in the compile command will match the two files SpiralGeneratorTester.java and SpiralGenerator.java.For the larger program we are doing for this assignment (for that one main is in SpiralViewer.java), you can either list all of the files it uses on the command line or use the following convenient shorthand:
javac @SpiralViewer.list java SpiralViewerThe SpiralViewer.list file (one of your starter files) just consists of the list of files to compile for the program. The @ on the command line tells javac to look in the file that follows it to find out what java files to compile. An alternate is to use *.java instead in the compile command, although that one would also attempt to compile SpiralGeneratorTester.java as well as the code for the car example.
So, what should you put in your SpiralGeneratorTester? This will be a console-based program -- i.e., no GUI. It will be a non-interactive program (i.e., fixed data, nothing read in from the user) that tests every method multiple times, printing informative output to the console with the results of each operation.
For a SpiralGenerator with given parameters you can predetermine what all the output will be. But instead of comparing with reference output (that you'd likely have to compute by hand), in your tester you're going to just test a subset of what has to be true for a spiral.
Here are the requirements for your test program:
. . . Making a spiral starting from java.awt.Point[x=200,y=300] with a unit length of 5, and made up of 10 segments: Segment #1: Point2D.Double[200.0, 300.0] Point2D.Double[205.0, 300.0] Segment #2: Point2D.Double[205.0, 299.0] Point2D.Double[205.0, 294.0] FAILED: last two segments are not connected . . . Segment #4: Point2D.Double[195.0, 295.0] Point2D.Double[205.0, 305.0] FAILED: segment is not horizontal or vertical. Skipping pair tests. . . . Segment #6: Point2D.Double[210.0, 305.0] Point2D.Double[210.0, 290.0] Segment #7: Point2D.Double[210.0, 290.0] Point2D.Double[210.0, 305.0] FAILED: last two segments are not perpendicular . . .About your tester output and the example shown above:
Note: When you test a method such as the SpiralGenerator constructor, which has a restriction on its parameter (in this case the restriction is that the unitLength must be greater or equal to one) it means that the behavior of the method is undefined if that precondition is not met. Your test program should not attempt any tests that violate preconditions on methods.
We will test your SpiralGeneratorTester with our own buggy SpiralGenerator classes.
The JComponent methods, getWidth() and getHeight(), which get the width and height of the component, will come in handy here. Since SpiralComponent is a subclass of JComponent you can directly call those methods from your component object. For an example of such calls, see the CarComponent class included in the starter code (and discussed further here).
Printing lines and points
Most Java classes have a
toString method defined that returns a String form of the
object, useful for printing its contents; even better, if we pass an
object that has toString defined to a print or println
statement, this toString method will get implicitly called. However,
for some reason Line2D.Double does not have a
toString that does what we want, so if you want to print a line,
you'll have write code to print the points it contains. Here's some example code
to print a segment returned by our nextSegment() method.
getP1 and getP2 are Line2D methods
(which means they also work for Line2D.Double).
Line2D currSeg = gen.nextSegment(); System.out.println(currSeg.getP1() + " " + currSeg.getP2());Here's some sample output from that statement:
Point2D.Double[215.0, 310.0] Point2D.Double[215.0, 285.0]
Recall that you never will be calling paintComponent yourself, nor are you allowed to change the parameters to it.
Style. We have published a more complete set of style guidelines for the course on the assignments page, but here are a few things to pay particular attention to for this program:
Implementing the required class design will also be part of your style/documentation score.
The files you need to submit are the ones shown in bold in the earlier section on assignment files.
No matter where/how you developed the code, we will be grading it on Vocareum using the java compiler and virtual machine there (Version 1.8, aka Java 8).
If you developed your program outside of Vocareum, for example, using Eclipse on your laptop, you'll need to upload your code to Vocareum and recompile and retest it completely before you submit it. Do not wait until the final due date/time is imminent before testing it on Vocareum. Please read the earlier section on using another IDE for more details on this.
How to submit your program When you are ready to submit the assignment press the big "Submit" button in your PA1 Vocareum work area. Do not wait until the final due date/time is imminent before attempting to submit for the first time. You are allowed to submit as many times as you like, but we will only grade the last one submitted.
What happens when you click submit. Vocareum will check that you have the correct files in your work area and whether they compile. It will also check whether the segments generated by your SpiralGenerator class are correct for a very small spiral. Passing these submit checks is not necessary or sufficient to submit your code (the graders will get a copy of what you submitted either way). (It would be necessary but not sufficient for getting full credit.) However, if your final submitted code does not pass all the tests we would expect that you would include some explanation of that in your README. One situation where it might fail would be if you only completed a subset of the assignment (and your README should document what subset you completed.)
The results of the submit checks will appear on your terminal window. You can also access them by going to the "Details" menu, and choosing "View Submission Report". (Like we did on Lab 1.) Please read this report to see if you passed the tests, so you can fix your program and resubmit if necessary. Make sure you scroll down to the bottom of the report so you don't miss anything.
If you are unsure of whether you submitted the right version, there's a way to view the contents of your last submit in Vocareum after the fact: see the item in the file list on the left called "Latest Submission".
