This document describes how to obtain, install, and use the starter kit. Also included in this document is a brief description of the contents of the project starter kit, but more detailed information is available in the JavaDoc formatted documentation included in the starter kit as well as available on the class web page.
The started kit is available for download here. (You might need to right-click on this link to save the starter kit.)
Once you have downloaded the starter kit, you must install it. The starter kit is simply packaged as a Java JAR file, which is similar to a ZIP file. To extract the contents of the starter kit, in the directory where you want your project to reside type:
jar xf starterkit.jar
This commands extracts the contents from the file; the result is that you will have a new directory, called concurrent, in your current directory. The concurrent directory contains everything that is needed for the project. (In order to use the jar command, you must have installed the Java Development Kit (JDK) and have its commands in your PATH variable; this should already be the case if you are using the Linux computers at school.)
The concurrent directory contains the following files and directories:
Most of these files do not need to be edited, the files that definitely need to be edited are MyRobot.java and WorldServiceActivator.java, although you should also provide your own icon (20 x 20 pixel) for your robot.
The source code contained in the starter kit all compiles and packages into components correctly, you can even install and run the included components, but they do not do much. I can almost guarantee that there are bugs somewhere in the starter kit, so please report any bugs to me.
You can use the build scripts to automatically compile and package your code, but in order to use these scripts you must make sure that you keep the Java files in the directories above. If you add a file, you must also add it to the appropriate directory; the directories represent Java packages and therefore require that if you add a class to them that you also put them in the proper package. For example, if you wanted to create an additional Java file for your robot implementation, called Foo.java, you must put Foo.java in the robot directory and the package specified inside of the Foo.java file should be "package robot;".
The build scripts perform two actions, they compile your Java files and write the generated class files into the classes/ directory and they package your classes as a JAR file and put it into the jars/ directory. For example, when you run build-world.sh, upon successful completion of the script, you will have a world.jar file in the jars/ directory.
IMPORTANT: The robot depends on the world, so you must create a world.jar file in order to build a robot.jar file. It is possible to successfully build both world.jar and robot.jar with a clean starter kit and both JAR files are included in the kit.
Use the run script to run Oscar. Oscar is an environment for loading components, like the components we are creating in the world.jar and robot.jar files above. Once you have started Oscar, you will be prompted for a profile name, you can use any name you want and have as many profiles as you want; a profile is just a disk area where you can load and save components. After you have enter a profile name, you will be at the Oscar shell prompt; to see a list of possible commands type help.
You do not need to know a lot about Oscar, the only things you need to know are that you can install components, start components, stop components, and uninstall components. For example, if your world.jar file is in c:\projects\concurrent\jars\, then to install the component, you would type:
-> install file:/c:/projects/concurrent/jars/world.jar
This would install the component into Oscar; if you want to see the components you have installed, type ps and you will see something like this:
-> ps
[ 0] [Active ] System Bundle
[ 1] [Installed ] file:/c:/projects/concurrent/jars/world.jar
->
The first number in this above list is the component identifier and the second column is the status of the component. If you want to start the world component, you would simply type:
-> start 1
This would start the world component, which causes WorldServiceActivator to register the WorldService implementation with Oscar. Installing and starting the robot.jar component is performed exactly in the same manner; starting the robot component causes the MyRobotActivator to create an instance of MyRobot and register it with WorldService.register(). In order to install and start a component in a single step, you can just type the URL at the Oscar shell prompt and then Oscar will first install the component and will then automatically start it. To stop a component, just use the stop command with the component indentifier.
IMPORTANT: Since robot.jar depends on world.jar, you must have world.jar installed before you try to start robot.jar; if not, the shell will report a dependency error.
Loaded components and their status is saved in your profile, so if you run Oscar again and use the same profile, then any components that you had previously loaded will be loaded again. To remove a component from a profile, you must use the uninstall command with the component identifier. After uninstalling a component, you will still be able to see it if you type the ps command. In order to actually remove the component either type refresh or exit with the shutdown command and restart Oscar. You will need to repeatedly install and uninstall your component implementation while you are developing and testing your solution. You can also use the update command to update a component implementation, like this:
-> update 1 file:/c:/projects/concurrent/jars/world.jar
-> refresh
The update command will install the updated JAR file and the refresh command will stop, reload, and restart any dependent components; you must perform a refresh for the update to take affect. If, after updating a component, you are not getting the behavior you expect, then try exiting Oscar and restarting it since our components maintain state that may become invalid across updates.
Since the GUI for drawing the maze is not yet created, I have made a simple
component that you can use to start the game and test your code; it is called
ui.jar and is in the jars/ directory. The ui.jar component also depends on world.jar, so you must load world.jar before you can start ui.jar. The ui.jar component simply displays a window with a button to start the game and a button to print an ascii dump of the maze.