CSCI 201 Lab 2 -- jGRASP

This week we are going to show you how to use jGRASP, a Java IDE (Integrated Development Environment) developed at Auburn University. Because jGRASP itself is written in Java, it can run on any platform that supports Java. That's how we are able to use the same IDE with both Linux and Windows.

We will only describe a few features of jGRASP in CSCI 201. To become a jGRASP guru, you should consult the draft jGRASP Handbook which may be found on the CD-ROM bundled with your textbook or downloaded from the GRASP project home page.

Starting jGRASP

Windows users may start jGRASP via the usual start button. Linux users can start a terminal session and then type the command "jgrasp". Linux users may also configure GNOME to start jGRASP through the menu system. We won't discuss that here.

First view -- Windows

In Windows, jGRASP will bring up two different windows. Usually, the first is a jGRASP Control Shell. You can probably ignore it unless jGRASP is "hung". In that case, you may want to raise this window and press the button labeled "Shut Down jGRASP, Forcibly if Necessary".
jGRASP Control

The real jGRASP window usually covers up the jGRASP Control Shell. By default, it starts running the Windows look and feel.
jGRASP Windows

Because we want to use the Metal (Java Swing) look and feel in our examples, go through the SettingsLook And FeelMetal selections of the menu bar to achieve Metal.

First view -- Linux

Linux jGRASP also starts with two initial windows. The first
Linux jGRASP control
is a small window that is actually displayed by a small C program used to control jGRASP. You can ignore this window unless you need to terminate jGRASP.

The second window gives an ominous disclaimer about "bugs".
Linux jGRASP warning
Just press the Don't Show Again button and go about your business. Soon the Metal interface will be displayed.

The Metal user interface

Windows or Linux, you ought to see something like this:
Metal interface

Creating a project

jGRASP, like many IDE's, uses projects to organize programming tasks. A project is a collection of related programs used to solve a problem. Although you really don't need projects in your early CSCI 201 assignments, you might as well get into the habit of using them.

Our standard project directory

In the Windows labs, we'll be storing our projects in subdirectories of the C:\Files directory. These projects will be lost whenever you reboot one of the UNCA lab computers, so you probably want to know how to transfer these to a floppy disk.

In the Linux world, projects will be stored in subdirectories of your personal csci/201 directory. Although these projects will persist between Linux login's, you need to know how to transfer these projects to a floppy if you want to take them home.

Getting to the standard directory

First follow the menu bar choices ProjectsNew Project ... to bring up the New Project dialog. This dialog is built with the Java Swing file search interface. There are two boxes near the words "Look In". The box to the right can be used to move down the directory hierarchy (toward the root) or to move to different drives. The much larger box, which is below Look In, is used to move into subdirectories.

Unix Windows
Linux directory Windows directory

Linux users should now head toward csci/201; and Windows users, toward C:\Files. If you are having trouble following the route, you might check out our Extremely Tedious and Detailed Guide to jGRASP Directory Search.

Creating a new subdirectory

In our labs, we're going to create a new subdirectory for each project. We recommend you also follow this practice in your programming assignments. To do this, press on the icon that vaguely looks like a file folder, New Folder icon. When you pass your mouse over this icon, the words "Create New Folder" should appear.

A new folder called New Folder will appear. Rename this new folder Lab2a. This maneuver can be difficult for even the most experienced Windows or Linux user. You must gently and patiently click the words "New Folder" until they are highlighted. Then you can edit the file name. If you are getting very frustrated in your renaming, check out our Extremely Tedious and Detailed Guide to jGRASP Directory Creation.

Double click on your newly created Lab2a to move in. Finally, type the word "Lincoln" into the text box labeled File Name and click the button labeled Create. A new project named Lincoln.gpj will be created.

If you look in the left pane with the Browse tab selected, you should see something resembling the following:

Unix Windows
Linux browse Windows browse

jGRASP project creation checkoff

This is your first checkoff point. Show your lab instructor your jGRASP window, so that he/she can verify that you have created the project in the right directory.

Creating a Java file

Yes, it's finally time to actually create a Java file in jGRASP. First you must create an new CSD, or Control Structure Diagram, window for the code. Do this from the menu bar as FileNew FileJava.

The new CSD window will appear in the right pane. Notice that the CSD window has its own title bar and menu bar. Note that menu bars of both the main jGRASP window and the CSD jGRASP window have a choice labeled File. This can get confusing.

You'll probably want the CSD window to fill the right pane. Mash the CSD's Maximize icon, Maximize, to make this happen.

Cut and paste the following familiar Java program into the CSD window using the CSD's EditPaste.

public class Lincoln
   public static void main (String[] args)
      System.out.println ("A quote by Abraham Lincoln:");
      System.out.println ("Whatever you are, be a good one.");

Using the CSD's FileSave As ... menu choices, save your Java code in the file within the Lab2a directory.
Saved File

If you are using Windows, you should save your file in "Binary/Unix" format. If you don't you will discover that, when you reload your Java program into jGRASP, the two-letter "word" OD will appear at the end of each line. This is actually, 0D (zero-D) the hexadecimal representation of the enter key. You may consider this a jGRASP bug.

Binary save

Adding your code to the project

Follow the CSD's FileAdd to ProjectRelative Path trail to actually add your Java code to the project.

If you press the Project tab of the right pane, you should now see your Java program associated with the jGRASP project.

Project view

Compiling your Java code

At last it's time to generate some bytecode. You have three choices for doing this.

  1. Press the CSD's Compile File icon, Compile icon
  2. Navigate the CSD's CompilerCompile menu selections
  3. Type control-B

The bottom panel of jGRASP should display a message that indicates successful compilation of your program. If it doesn't, you need to get the attention of your lab instructor.

Running your Java bytecode

You have three ways to run your program.

  1. Press the CSD's Run application for current file icon, Run icon
  2. Navigate the CSD's RunRun menu selections
  3. Type control-R

The bottom panel of jGRASP should automatically select the Run I/O tab and display the output of your program.

jGRASP program checkoff

Show your lab instructor the result of running your program.

Exiting jGRASP

Use the "main" jGRASP window to terminate jGRASP. Linux users may also have to terminate the smaller jGRASP control window.

Saving your project to a floppy disk

We all know floppy disks are a somewhat dated way to transfer data, but they'll do in a pinch.

Transferring your project under Windows

Bring up the file explorer. If you don't remember how, you can always review CSCI 201 Lab 1.

Once file explorer is running, navigate through the left pane to the directory C:\Files. The contents of C:\Files should then be displayed in the right pane. Now press on the icon for Lab2a and drag it over to the A:. Double-click on A:\ to make sure the move was successful.
Selecting Lab2a Moving Lab2a to A: Checking A:

Transferring your project under Linux

First of all, it is recommended that you format your floppy disk on a PC running Windows before using it on the Linux computer. After you place a floppy disk into your Linux computer, the root directory of the floppy disk will appear as the directory /mnt/floppy as soon as you mount it. Then you can use the cp -R, copy recursively, command to move all the files of a specified directory to the floppy disk. Next, use ls -R, list recursively, to view the entire contents of the floppy disk. Finally, unmount your disk. Here are the commands for performing the transfer to floppy disk. Notice that the last command is "umount", not the more natural "unmount".

[XXXX@YYYY ZZZZ]$ mount /mnt/floppy
[XXXX@YYYY ZZZZ]$ cp -R csci/201/Lab2a /mnt/floppy
[XXXX@YYYY ZZZZ]$ ls -R /mnt/floppy
[XXXX@YYYY ZZZZ]$ umount /mnt/floppy

Project transfer checkoff

Show your lab instructor that you have copied your project directory to your disk.

Downloading a Java archive

In this course you're must frequently download collections of files for use in labs and assignments. We're going to use jar, or Java archive, files for this purpose in CSCI 201.

In your browser click on the following link for the Java archive for part B of Lab 2. We recommend that Windows users save the file in C:\Files; and Linux users, in csci/201.

Restart jGRASP. Use the ProjectJar / Zip Extractor ... menu choices to bring up the jar extractor dialog. Now use the FileOpen Jar or Zip File ... menu path of the jar extractor dialog to bring up an Open File dialog. Navigate to the directory where you copied the jar file, select it, and open it.
Open jar dialog

Now the jar extractor dialog shows the files that may be extracted.
Files in Jar file

Take the FileExtract Files ... menu choice to bring up an Extract to Directory dialog box. Create the new directory Lab2b for your files and press Extract. Your files should be waiting as soon as you exit this dialog.
Extract dialog

Opening the project

Use the ProjectOpen Project ... menu choices to open project Lab2b . Select the Project tab of the left pane and then double-click on the entry. A CSD windows containing Java code should appear in the right pane. You'll probably want to maximize the CSD window.
Lab2b project
Ignore the jGRASP message that your files may have been edited outside of the control of jGRASP.

jGRASP jar extraction checkoff

Show your lab instructor that you have extracted your project into the right directory.

Yes, there are a lot of checkoff points in this lab. We're just trying to make sure you get started on the right track.

Fixing compile bugs

Now compile the program. (Remember, either Compile icon or control-B.)

Oops. There's a error in our program. jGRASP is very helpful here. It highlights the Java compiler messages in green and tries to display the offensive Java statement on a black background.
Compiler error

Fix the program by adding a semi-colon to the end of the bad line of Java. Re-compile.

Fixing a simple run-time bug

Run the program. (It's Run icon or control-R.)

This time the bottom pane displays a run-time error:

java.lang.NoSuchMethodError: main
Exception in thread "main"

The problem here is that the main method is called Main, rather than main. Fix, re-compile, and re-execute.

Today is Tuesday

Preparing for a break

So you ran the program and saw the output. Wouldn't it be more fun to see the Java code be executed a line at a time. This is something we can do with the debugger.

First, we must recompile the program in debug mode. Use the CompileDebug Mode menu path to enable debugging. Then re-compile your program.

Debug mode setting

Now you must set a breakpoint in your program to interrupt normal program execution. Do this by clicking your cursor anywhere within the line that says:

      for (int i=0; i<7; ++i)

Next right click within the CSD window. You should see a new pulldown menu. Select Toggle Breakpoint. A right circle should appear to the right of the selected line.

Be careful not to select Toggle Bookmark.

Setting breakpoint

Making a break

Press the debug icon, Debug icon, or use the RunDebug menu choice, to start executing your program with the Java debugger. You program should immediately halt.

Make sure the Debug tab is selected in the right pane. You should see four separate displays in this pane.

The first is a row of debugging control icons. Move your mouse slowly across this row to get a brief description of what each does. We'll only use the leftmost icon, the downward pointing arrow, in this lab. Each time it is clicked, one statement of your program will be executed. Go ahead and click it a few times.

Debug control buttons

The next is a display of threads. Java can use thread to simultaneously execute several methods. This is important in networking and animation applications and you may learn to write multi-threaded Java code in upper-level CSCI courses.

Debug thread display

The third display is the call stack. Right now you see that the main method of class TryIt is being executed. This display gets more interesting when methods call other methods.

Debug call stack display

You'll notice that the final display has two tabs. Presently you should be on the variables tab. This display will probably be the most helpful to you because it shows you the values of the variables being used by your class and method. Step through your program and see how the value of i changes. See how the words "Today is" are output.

Debug variable display

jGRASP debugging checkoff

Show your lab instructor that you can step through your program

Isn't that enough

Go home.