The GridWorldCase 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 MethodsGo

Go

Go

Go

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

RockBug 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 VariablesThe 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<Actor> 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<Actor> 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<Actor> 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<Actor> 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 placedpublic void putSelfInGrid(Grid<Actor> 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 actorpublic 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<Actor> 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<Actor> 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, & getThese 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 <Location> 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 <Location> getValidAdjacentLocations(Location loc);

XX X

XX XX 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 <Location> getEmptyAdjacentLocations(Location loc);

X

XXX

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 <Location> 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 <E> getNeighbors(Location loc);