The GridWorld Case Study Program Section 1 - Overview of the Class Hierarchies Section 2 - The Actor Class Section 3 - The Rock and Flower Classes Section 4 - The Bug Class Section 5 - The Grid Interface and Its Methods Go

GridWorld Section 1 Overview of How the Classes are Organized

What is the GridWorld Case Study Program The GridWorld Case Study Program provides a graphical environment where objects (called actors) inhabit and interact in a two-dimensional grid. One of the purposes of GridWorld is to provide a means for the study of inheritance and the interaction between Java classes … specificially the interaction between super classes and sub classes. On the AP Exam, you can expect there to be … at least 5 Multiple Choice Questions and 1 Free Response Question about GridWorld. This amounts to 3/8 of the AP Exam.

The GridWorld Hierarchies The GridWorld Case Study Program organizes the class files into two main hierarchies: 1)The Actor Hierarchy that organizes the characteristics and behavior of actors. 2)The Grid Hierarchy that organizes the data structures that will contain and manipulate the actors.

The GridWorld Actor Hierarchy Actor Class Rock Bug Critter BugRunner Runner classes are driver files that set up ActorWorlds that can contain the above actors. Flower BoxBug ChameleonCritter Crab Critter CircleBug ZBug SpiralBug DancingBug ChameleonKid

The Grid Hierarchy Grid Interface BoundedGrid Class AbstractGrid Class UnboundedGrid Class Students only need to know the Grid API. What that means is you need to know how to call the methods in the Grid interface by looking at their method signatures. You don’t need to know anything about the code in the methods. The code for all of the methods are either in the AbstractGrid class or its subclasses: BoundedGrid and UnboundedGrid.

GridWorld Section 2 The Actor Class

The Actor Class Instance Variables The Actor class defines the base characteristics and behavior of any actor. It contains the code that any kind of Actor needs, whether it is a Bug, Rock, Flower, or Critter. The Actor class is not an Abstract class but it could be and fulfills what we know an Abstract class should do. Here is the initial part of the code for Actor: public class Actor { private Grid grid; private Location location; private int direction; private Color color; Notice that an Actor has a Grid that it is associated with and a location within that Grid. It also has a direction that it is facing and a color.

The Actor Class Constructor public class Actor { private Grid grid; private Location location; private int direction; private Color color; // The Constructor instantiates a blue actor that is facing north. // It is not until an actor is added to an ActorWord that it is // associated with a particular Grid and given a Location in the Grid. public Actor() { color = Color.BLUE; direction = Location.NORTH; grid = null; location = null; } In the info.gridworld.actor package, you can open the Actor class and view its full code.

The Actor Instance Variables grid & location public class Actor { private Grid grid; private Location location; private int direction; private Color color; One of the most important things you need to realize is that because every instance of Actor has a grid and a location, all of the methods of the Grid interface can be called with grid and all of the methods of the Location class can be called with location. Another thing that is important to realize is that the Actor class defines the general characteristics for any subclass that extends Actor. Therefore, we don’t really want to construct objects of the Actor class but rather we want to construct objects of its subclasses. However, looks look at the remainder of the methods in the Actor class.

The Actor Class Accessors & Mutators Since all Actor objects need these methods, there is no reason to have them in the subclasses. It makes sense to have these methods one time in the Super class. // Gets the color of this actor. public Color getColor() { return color; } // Sets the color of this actor. public void setColor(Color newColor) { color = newColor; } // Gets the current direction of this actor. public int getDirection() { return direction; } Any subclass can call these methods!

Other Actor Class Accessors & Mutators // Sets the current direction of this actor. The direction of // this actor is set to the angle between 0 and 359 degrees // that is equivalent to newDirection. Example: 400 degrees equals 40. public void setDirection(int newDirection) { direction = newDirection % Location.FULL_CIRCLE; if (direction < 0) direction += Location.FULL_CIRCLE; // -100 degrees equals +260 } // Returns the grid in which this actor is located or null if this // actor is not contained in a grid. public Grid getGrid() { return grid; } // Returns the location of this actor or null if this actor is not // contained in a grid. public Location getLocation() { return location; }

The Actor Class Method putSelfInGrid // Puts this actor into a grid. If there is another actor at // the given location, it is removed. // Precondition: (1) This actor is not contained in a grid // Precondition: (2) loc is valid in gr // gr the grid into which this actor should be placed // loc the location into which the actor should be placed public void putSelfInGrid(Grid gr, Location loc) { if (grid != null) throw new IllegalStateException("This actor is already contained in a grid."); Actor actor = gr.get(loc); // get actor already at this loc if (actor != null) // if there is really an actor & not null actor.removeSelfFromGrid(); // remove the old actor gr.put(loc, this); // add this actor to the location loc grid = gr; // make sure the actor is associated with grid location = loc; make sure this actor knows it is at loc }

The Actor Class Method removeSelfInGrid // Removes this actor from its grid. // Precondition: This actor is contained in a grid public void removeSelfFromGrid() { if (grid == null) throw new IllegalStateException("This actor is not contained in a grid."); if (grid.get(location) != this) throw new IllegalStateException("The grid contains a different actor at location ” + location + "."); grid.remove(location); // remove actor at Location location grid = null; // disassociate actor with previous grid location = null; // disassociate actor with previous location }

The Actor Class Method moveTo // Moves this actor to newLocation. If there is another actor at the // given location, it is removed. // Precondition: (1) This actor is contained in a grid // Precondition: (2) newLocation is valid in the grid of this actor public void moveTo(Location newLocation) { if (grid == null) throw new IllegalStateException("This actor is not in a grid."); if (grid.get(location) != this) throw new IllegalStateException("The grid contains a different actor at location " + location + "."); if (!grid.isValid(newLocation)) throw new IllegalArgumentException("Location " + newLocation + " is not valid."); if (newLocation.equals(location)) return; // locations are the same so no need to change anything grid.remove(location); // remove the actor from its present location Actor other = grid.get(newLocation); // get actor at new location if (other != null) // if there is an actor at new location other.removeSelfFromGrid(); // remove actor from new location location = newLocation; // set the location of the moving actor grid.put(location, this); // place moving actor in the grid at its new location }

The Actor Class Method act // Reverses the direction of this actor if this method is not overridden in subclasses. public void act() { setDirection(getDirection() + Location.HALF_CIRCLE); } This method simply takes the direction of the Actor and adds 180 degrees to it to reverse its direction.

The Actor Class Method toString // Creates a string that describes this actor. The string // returned identifies the location, direction, and color of // this actor. public String toString() { return getClass().getName() + "[location = " + location + ", direction = " + direction + ", color=" + color + "]"; } Outputting the identity of the grid would be meaningless since no clear identification system for grids exists.

GridWorld Section 3 The Rock and Flower Classes

The Rock Subclass of Actor public class Rock extends Actor { private static final Color DEFAULT_COLOR = Color.BLACK; // Constructs a black rock. public Rock() { setColor(DEFAULT_COLOR); } // Constructs a rock of a given color. public Rock(Color rockColor) { setColor(rockColor); } // Overrides the act method in the Actor class and makes a // Rock do nothing. Notice there is no code in the method! public void act() { } The Rock class is probably the simplest of all Actor subclasses.

The Flower Subclass and Its Constructors public class Flower extends Actor { private static final Color DEFAULT_COLOR = Color.PINK; private static final double DARKENING_FACTOR = 0.05; // Constructs a pink flower. public Flower() { setColor(DEFAULT_COLOR); } // Constructs a flower of a given color. public Flower(Color initialColor) { setColor(initialColor); }

The Flower Subclass act Method // Causes the color of this flower to darken. // The darkening factor helps a flower lose 5% of its color // value during each step when a program is running. public void act() { Color c = getColor(); int red = (int) (c.getRed() * (1 - DARKENING_FACTOR)); int green = (int) (c.getGreen() * (1 - DARKENING_FACTOR)); int blue = (int) (c.getBlue() * (1 - DARKENING_FACTOR)); setColor(new Color(red, green, blue)); } Since you have probably seen a GridWorld program run at this point, you realize that during each step of a program, the act() method is called and executed for every Actor!

GridWorld Section 4 The Bug Class

The Bug Subclass and Its Constructors public class Bug extends Actor { // Constructs a red bug. public Bug() { setColor(Color.RED); } // Constructs a bug of a given color. public Bug(Color bugColor) { setColor(bugColor); }

The Bug Subclass act & turn Methods // Moves if it can move, turns otherwise. public void act() { if (canMove()) move(); else turn(); } // Turns the bug 45 degrees to the right without changing its // location. This method is executed when a Bug cannot move. public void turn() { setDirection(getDirection() + Location.HALF_RIGHT); }

The Bug Subclass move Method // Moves the bug forward, putting a flower into the location it // previously occupied. // NOTE: the else clause below is protection in case canMove() // is not called before calling move() and the Bug is at the // edge of the grid. public void move() { Grid gr = getGrid(); if (gr == null) // if Bug not associated with a grid don’t move return; Location loc = getLocation(); // get current location of Bug Location next = loc.getAdjacentLocation(getDirection()); if (gr.isValid(next)) // if location straight ahead is valid moveTo(next); // move Bug to location straight ahead else // if location is not valid remove Bug from grid removeSelfFromGrid(); Flower flower = new Flower(getColor()); flower.putSelfInGrid(gr, loc); } construct Flower of Bug’s color and put it in Bug’s old location.

The Bug Subclass canMove Method // Tests whether this bug can move forward into a location that // is empty or contains a flower. Returns true if this bug can // move. public boolean canMove() { Grid gr = getGrid(); if (gr == null) // if Bug not associated with a grid it can’t move return false; Location loc = getLocation(); // get current location of Bug Location next = loc.getAdjacentLocation(getDirection()); if (!gr.isValid(next)) // if location straight ahead is NOT valid return false; Actor neighbor = gr.get(next); // get actor in location ahead return (neighbor == null) || (neighbor instanceof Flower); // if the location straight ahead is empty (contains null) or // contains a Flower then Bug can move there so return true. }

GridWorld Section 5 The Grid Interface and Its Methods

The Grid Interface The Grid Interface organizes the methods for the AbstractGrid class and its two subclasses BoundedGrid and UnboundedGrid. Students just need to know how to call the methods of the Grid interface by looking at their method signatures. Don’t worry about the code. Grid Interface BoundedGrid Class AbstractGrid Class UnboundedGrid Class

The Grid Methods getNumRows & getNumCols Since a Grid in most cases is a two-dimensional array, its seems natural that the two methods getNumRows & getNumCols return exactly what we expect: // Returns the number of rows in this grid or -1 if this grid // is unbounded int getNumRows(); // Returns the number of columns in this grid or -1 if this // grid is unbounded int getNumCols(); Because an UnboundedGrid has an unspecified size, the value -1 is returned for both of these methods.

The Grid Method isValid // This method checks whether a location is valid in this grid. // Precondition: loc is not null. // Returns true if loc is valid in this grid, otherwise false. boolean isValid(Location loc); If we pass isValid the Location represented by (9, 1) where the red bug is, then true will be returned. However, if we pass isValid (10, 1), the location immediately below the red bug which is out of bounds, then it will return false. It is possible to construct a bug and try to add it outside a Grid. This will result in an error.

The Grid Methods put, remove, & get These three methods allow you add, remove, or obtain actors from the Grid. // Puts an object obj at a given location in this grid. // Precondition: loc is valid in this grid and obj is not // null. Returns the object previously at loc or null if the // location was previously unoccupied. E put(Location loc, E obj); // Removes the object at a given location loc from this grid // and returns it or null if the location is unoccupied. // Precondition: loc is valid in this grid. E remove(Location loc); // Returns the object at a given location loc in this grid or // null if the location is unoccupied. // Precondition: loc is valid in this grid. E get(Location loc);

The Grid Method getOccupiedLocations This method returns an ArrayList of all the locations in the Grid that are occupied by actors. For the grid seen here, the twelve different locations that hold the twelve actors will be returned in an ArrayList of Locations objects. ArrayList getOccupiedLocations();

The Grid Method getValidAdjacentLocations This method would return an ArrayList of locations values marked by the adjacent blue Xs for the yellow bug at the Location loc. It would return an ArrayList of locations values marked by the adjacent red Xs for the red bug with the Location loc. The location loc must be valid in this grid. No invalid locations surrounding a bug will be in the list. ArrayList getValidAdjacentLocations(Location loc); X X X X XX X X X X X XX

The Grid Method getEmptyAdjacentLocations This method gets all of the valid empty locations adjacent to a given location in all eight compass directions. This method would return an ArrayList of location values marked by the red Xs for the Critter with the Location loc. The location loc must be valid in this grid. ArrayList getEmptyAdjacentLocations(Location loc); X X X X

The Grid Method getOccupiedAdjacentLocations This method returns a list of the valid occupied locations adjacent to the Critter. In the graphic seen, an ArrayList of location values where the Rocks are would be returned. Notice that the Rocks are adjacent to the Location loc, where the Critter is located. The location loc must be valid in this grid. ArrayList getOccupiedAdjacentLocations(Location loc);

The Grid Method getNeighbors This method gets a list of the neighboring occupants in all eight compass directions that are adjacent to loc, where the Critter is located. Specifically, it returns an ArrayList of Actors in the valid adjacent occupied locations. The location loc must be valid in this grid. ArrayList getNeighbors(Location loc);