Project 5 - Addendum

CIS 211 - Computer Science II - Winter, 2003 - A. Hornof

Modifications and advice for Project 5 are listed here in reverse chronological order, with new additions at the top.

3/3/03 - Q: Should the command input be case sensitive?

Sure. It's easier to program, and that's how Unix does it.

You may add more informative error messages.

You may provide additional error messages that provide more-detailed feedback, but please follow the example of those that are specified. Please keep them very brief and to the point.

3/2/03 - Removed the unnecessary call to getInstance() in the P4.java "try" block.

Q: There was a call to getInstance() when calling stringListToModel() in the P4.java "try" block, but it is no longer there in the P5.java "try" block. Why not? P4.java had

	(MaritimeModel.getInstance()).stringListToModel(stringList);

but P5.java has

	MaritimeModel.stringListToModel(stringList);

A: Since stringListToModel() and modelToStringList() should have been defined as static (they were specified as "class methods" in Project 4), either of these lines of code would do the same thing because of an ugly little detail in Java that you can call a static method with either the name of the class OR an instance of the class. So, if stringListToModel() really is static, the extra characters in the second line above are not only unnecessary and do nothing, but they also potentially confuse the programmer into thinking that stringListToModel() is an instance method when it is really a class method.

2/26/03

Design your own getters, setters, and other methods

We will continue to maintain and update a list of suggested setters, getters, and other methods that you might want to use in your project, but you no longer need to adhere to this list. Originally, we were asking you to use this list for strong "cohesion" between your code and ours, and so that we could swap out one of our modules with one of yours when grading. We are no longer limiting you to the method names, signatures, and functionalities listed here, and we will not swap our modules with yours when grading your projects.

However, when designing your own methods, you must do the following:

Stick to the functionality (i.e. the file formats, user interface, and ship-island interactions) described in the specification.
Stick to the filenames specified. The only files added to Project 4 should be P5.java, View.java, Controller.java, and ControllerException.java.
Comment your code so that the the functionality and responsibility of each method is clear and easily accessible when reading your code.
Design your methods maintaining, as much as possible, the integrity of the model, view, and controller. The model should hold all of the "world" data, including all ship and island information. The view should only concern itself with maintaining and displaying this one view of the model. The controller should handle all command processing during the running of the simulation.

Suggested setters, getters, and other methods

class MaritimeModel

setSail(Ship, Object, double) - Set up a sailing plan for a ship, with the Object as the destination.
plotAll() - Steps through all simObjects, plotting them in the view. Probably just used to initialize the view.
updateAll() - Steps through all the simObjects, calling the update() method for each.
describeAll() - Steps through all the simObjects, call the describe() method for each.

class SimObject

String getName() - Returns the name of the object.

class MaritimeModel

void plotAll() - Calls the View's plot(SimObject) method for every object in the world.
void updateAll() - Calls the update() method for every object in the world.
void describeAll() - Calls the describe() method for every object in the world.
void addView (View) - Gives the model access to the View object.
int getWorldSizeX()
int getWorldSizeY()
Ship getShip(String) - Returns the ship with this name, or throws a ControllerException if there is no ship with this name.
Island getIsland(String) - same as getShip() but for islands.
void setWorldSize(Location) - You might want to remove this setter. Since the world size is now (int, int) and Location is (double, double), it might not make sense to store the world size as a Location any more.
Location getWorldSize() - Similarly, you might want to remove this getter.

class View

public View() - The constructor should probably create the data structure behind the view. An ArrayList of ArrayLists is a fine way to go.
void plot (SimObject) - gets called by the MaritimeModel object. Adds the first two characters of each object name (or a "* ") to the correct cells of the data structure.

2/25/03

The "sail" command is simplified

The sail command will be simplified in the "Command Set". The modification is that the second two sail commands have been given unique command names.

sail <ship-name> <island-name> <speed>

Tell a ship to set sail to an island at a given speed.

sailcr <cruise-ship-name> <island-name-1> [island-name-2 ...] <speed>

Tell a cruise ship to set sail for any number of islands, in the order they are listed.

sailoc <pirate-ship-name> <X> <Y> <speed>

Tell a pirate ship to set sail to destination (X,Y).

2/24/03

Fuel levels and speeds should be displayed with two decimal points.

The following line, for example,

Island Hawaii (6.00, 1.00) has 200 tons of fuel.

should be

Island Hawaii (6.00, 1.00) has 200.00 tons of fuel.

Change units of fuel consumption rate

Change the units of the fuel consumption rate from "tons of fuel burned per nautical mile" to "nautical miles travelled per ton of fuel". This is an important change. It flips the measure.

Q: Can you please tell us how the data file is formatted in regards to what each token represents?

Sure. Good question. Here you go.

Ship  QE2  Cruise_Ship 12 10 12 0.1
Ship <Name> <ShipType> <Loc X> <Loc Y> <Max Speed> <Fuel Consumption Rate>

Island Cove 98.999 10.733 5.0002 0.1
Island <Name> <Loc X> <Loc Y> <Fuel Level> <Fuel Production Rate>

Q: This project is overwhelming! Where do I start?

A: Start by carefully reading the project specification (and this addendum) from beginning to end. It will help you to understand the scope of the project. Take notes as you go on interesting or unclear details. Sketch out the project and the interaction among the different modules as you go. When you are done, email 211staff@cs.uoregon.edu with any questions.

Then, decide which Project 4 code to start with. If you didn't get full credit, decide how quickly and easily you can fix your code, or whether you should use the solution provided.

After this, there are a number of ways to proceed. Here is how I am doing it:

Create the P5.java using the try block given below in this document. Comment out the lines that don't work yet.
Start by updating the MaritimeModel as specified in the "Model" section early in the handout (and which also extends a little into this Addendum). Use the new input and output formats listed below. Make sure your program creates a similar file, and that it can also use an output file that it generates as the input file on the next run, with no input formatting errors.
Create a tiny Controller that just accepts a few commands, including "quit" and "show".
Get the View working. Test it thoroughly, making sure labels line up correctly and ships and islands appear correctly all the way from 0 to 100.
One by one, get the various commands working.
Thoroughly test all possible ship and island interactions. Make a list on paper of all possible scenarios, and methodically go through one by one testing all situations.

P5.java

The try block in P5.java should include all of the following:

	try
	{

		// Read the file into the stringList.
		fileName = FileUtils.fileToStringList (fileName, stringList);			

		// Load the stringList into the model.
		MaritimeModel.stringListToModel(stringList);
			
		// Create a pointer the model
		MaritimeModel model = MaritimeModel.getInstance();

		// Create and initialize the view.
		View view = new View();
		model.addView(view);
		model.plotAll();
			
		// Create the controller.
		Controller controller = new Controller (model, view);

		// Run the simulation.
		controller.run();			
			
		// After the simulation, make sure the stringList is cleared.
		stringList.clear();

		// Save the model to the stringList.
		MaritimeModel.modelToStringList(stringList);

		// Save the stringList into the file.
		FileUtils.stringListToFile(stringList, fileName);
	}

2/23/03

World size

Three things:

The world size should still be stored and saved in the output file as two integers. Non-integer world size values in the data input file should still throw an error.
The maximum world size is now 101 x 101.
A correction: The updates to the Project 4 specify that "The world starts at (0, 0) and continues to (1-X, 1-Y)...." This should instead read "The world starts at (0, 0) and continues to (X-1, Y-1)...."

2/22/03

New input and output file formats

Here is a sample new input file: world.txt

Here is the output file that should be created from this input file after no ship movements: world-new.txt

Here is an input file with one error in each line: world-errors.txt. The errors for each line are as follows:

Misspelling
The world size parameters should be integers.
Any dimension over 99 is an illegal dimension for a world of 100x100.
The name "Cove" is reused.
Same as line 3.

Round doubles to two decimal points

All doubles should be rounded to two decimal points in the data file and in the screen printouts. A technique for accomplishing this is discussed in the Sun Java Tutorial. Do a google search on "java tutorial decimal format".

Interactions between Ships and Islands

Three corrections:

"If a ship is sailing... will arrive within 0.1 nm" SHOULD READ "within 1 nm".
CUT the following because a more descriptive message is defined in the next bulleted item.
```
<pirate-ship-name> has caught <ship-name>.
```
"When a pirate ship catches...(... within 0.1 nm...)" SHOULD READ "within 1 nm".