cs1705
Class World

java.lang.Object
  cs1705.TestableWorld
      cs1705.World

public class World
extends TestableWorld

This class can be used to build and maintain the world in which robots work and play.

This class is a subclass of the original kareltherobot.World class, with some enhancements. Most notably, it provides a startFromURL(String) method that makes it trivial to initialize the world from a URL, show the frame, and show the speed controls. Similar startFromFile(String) and startFromString(String) methods are also provided. The original class's readWorld() method was difficult to use within BlueJ.

You can save worlds in files and restore them. You can even create a world definition in a text editor. Information on the external form of worlds is available from Bergin's web site.

Version:

2003.08.20

Author:

Stephen Edwards

Method Summary

static int	delay() Return the current delay setting.
static World	getWorldAsObject() Returns the singleton instance of this class.
static String	getWorldDescription() Returns the configuration of the current world as a string.
static void	overrideNextStartUsingFile(String fileName) Define the file name to read a world description from on the next startFrom...() call.
static void	overrideNextStartUsingString(String world) Define the world description tu use on the next startFrom...() call.
static void	overrideNextStartUsingURL(String url) Define the URL to read a world description from on the next startFrom...() call.
static void	reset() Remove everything from the world and returns it to a pristine state.
static void	setDelay(int d) Slow down (or speed up) the operation of robots in the world.
static void	setSize(int numberOfStreets, int numberOfAvenues) Set the size of the world.
static void	setTrace(boolean tracingOn) Turns tracing on or off.
static void	setupThread(Runnable runnable) Sets up a runnable object (usually a robot) in a separate thread that will be executed in parallel with the world simulation.
static void	setVisible(boolean show) Show or hide the world's graphic frame.
static void	showSpeedControl(boolean show) Show or hide the speed dialog.
static void	startEmpty() Initializes Karel's world to be completely empty.
static void	startFromFile(String fileName) Initializes Karel's world by reading the world configuration file from the file indicated by the given file name.
static void	startFromString(String world) Initializes Karel's world from the given string.
static void	startFromURL(String url) Initializes Karel's world by downloading the world configuration file from a URL, given as a string.
static void	startThreads() Starts all of the threads associated with this world, so they begin executing in parallel.
static void	waitForRobotThreads() Wait until all concurrently executing robot threads have completed.

Methods inherited from class cs1705.TestableWorld

assertBeepersAt, assertBeepersAt, assertBeepersInWorld, assertBeepersInWorld, assertEWWallAt, assertNoBeepersAt, assertNoBeepersInWorld, assertNoEWWallAt, assertNoNSWallAt, assertNoRobotsInWorld, assertNSWallAt, assertRobotsInWorld, assertRobotsInWorld

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

delay

public static int delay()

Return the current delay setting. A lower delay means faster robots.

getWorldAsObject

public static World getWorldAsObject()

Returns the singleton instance of this class.

Returns:

a run-time object representing the world

getWorldDescription

public static String getWorldDescription()

Returns the configuration of the current world as a string.

Returns:

a string representing the current world

overrideNextStartUsingFile

public static void overrideNextStartUsingFile(String fileName)

Define the file name to read a world description from on the next startFrom...() call. This method is primarily useful for testing. Typically, a RobotTask will call World.startFrom...() to indicate the initial world configuration to use. Often, to fully test such tasks, you would like to start often with a different world (maybe several different worlds or start locations, each in a different test case). Using this method at the start of your test case allows you to "override" the behavior of the RobotTask's call to World.startFrom...() so that the world description specified here will be used instead.

Parameters:

fileName - a String object that contains an absolute or relative pathname indicating the file to read. The world file contents are then used to construct the world that Karel will navigate.

overrideNextStartUsingString

public static void overrideNextStartUsingString(String world)

Define the world description tu use on the next startFrom...() call. See the comments under overrideNextStartUsingFile(String).

Parameters:

world - A world description as a string

overrideNextStartUsingURL

public static void overrideNextStartUsingURL(String url)

Define the URL to read a world description from on the next startFrom...() call. See the comments under overrideNextStartUsingFile(String).

Parameters:

url - a String object that contains the fully qualified URL from which to read the world file. The world file contents are then used to construct the world that Karel will navigate.

reset

public static void reset()

Remove everything from the world and returns it to a pristine state.

setDelay

public static void setDelay(int d)

Slow down (or speed up) the operation of robots in the world. The lower you set the delay, the faster the robots run. A delay of zero may cause poor performance on older, slower systems.

setSize

public static void setSize(int numberOfStreets,
                           int numberOfAvenues)

Set the size of the world. The world itself isn't sized, just the visible portion of it. The default is 10 by 10.

setTrace

public static void setTrace(boolean tracingOn)

Turns tracing on or off. When on, robots will show their state on System.out after each action.

setupThread

public static void setupThread(Runnable runnable)

Sets up a runnable object (usually a robot) in a separate thread that will be executed in parallel with the world simulation. A robot that executes independently in its own thread should define its own run() method--the method that will be executed when the robot begins running independently.

setVisible

public static void setVisible(boolean show)

Show or hide the world's graphic frame. Initially, it is not visible.

showSpeedControl

public static void showSpeedControl(boolean show)

Show or hide the speed dialog. Initially, it is not visible.

startEmpty

public static void startEmpty()

Initializes Karel's world to be completely empty. Calling this method makes the world's graphic surface visible, performs a reset of the world's contents, and shows the speed control window.

startFromFile

public static void startFromFile(String fileName)

Initializes Karel's world by reading the world configuration file from the file indicated by the given file name. Calling this method makes the world's graphic surface visible, performs a reset of the world's contents, and shows the speed control window.

Parameters:

fileName - a String object that contains an absolute or relative pathname indicating the file to read. The world file contents are then used to construct the world that Karel will navigate.

startFromString

public static void startFromString(String world)

Initializes Karel's world from the given string. Calling this method makes the world's graphic surface visible, resets the world's contents, and shows the speed control window.

Parameters:

world - A world description as a string

startFromURL

public static void startFromURL(String url)

Initializes Karel's world by downloading the world configuration file from a URL, given as a string. Calling this method makes the world's graphic surface visible, performs a reset of the world's contents, and shows the speed control window.

Parameters:

url - a String object that contains the fully qualified URL from which to read the world file. The world file contents are then used to construct the world that Karel will navigate.

startThreads

public static void startThreads()

Starts all of the threads associated with this world, so they begin executing in parallel. Usually, these are separate robots with their own run() methods that have been set up using setupThread().

waitForRobotThreads

public static void waitForRobotThreads()

Wait until all concurrently executing robot threads have completed. This method, usually called from a main program or robot task, causes the program or task to wait until all robot threads passed into setupThread() have completed their execution. It can be used to ensure that a task doesn't terminate before all of the robots have finished their work.