Software Installation Instructions for SIGCSE2011 Workshop 19

Introduction

These notes describe five steps needed to get an Eclipse project using the Java ForkJoin Framework up and running. You may be able to skip steps because you already have things installed. It then provides files you should download and successfully run before the workshop. Using Eclipse is optional, but is known to work well. I had to follow all these steps myself on a new laptop and it took less than 30 minutes, but I've also done it before. Feedback welcome.

Java 1.6

You must have Java 1.6 (JDK 6). Java 1.5 and 1.4 will not work. I have no experience with experimental versions of Java 1.7. If you already have Java installed, a later step will make sure you are using 1.6. If you need to install 1.6, see http://www.oracle.com/technetwork/java/javase/downloads/index.html.

Eclipse (or not)

The Java ForkJoin Framework does not require any particular development environment, but I am most familiar with using it in Eclipse. If you get things working with your own preferred IDE, that's fine and I'd appreciate any information I can share with others. Using the command-line is also fine; some details for that appear later.

If you do not have Eclipse:

Download it from http://www.eclipse.org/downloads/
There is no installation other than extracting the files. Click on the eclipse executable to open it.
Choose a location for your workspace; the default should be fine.
Open the workbench view (click the arrow-looking icon on the right).

The ForkJoin Library

The library we are using is jsr166.jar, available at http://gee.cs.oswego.edu/dl/jsr166/dist/jsr166.jar. Download this file and save it somewhere.

If you have Eclipse Helios or a later release (you probably do), you can follow these simple instructions:

Create a new Java project in Eclipse (File, New, Java project).
Make sure Java SE-1.6 is the execution environment.
Drag and drop the jsr166.jar file onto the Java Project you just created in the Package Explorer window of Eclipse.
- Alternatively, instead of drag and drop, you can right-click on the project in the File Explorer, and select "Import... File System" and navigate to jsr166.jar, select it, make sure "Create selected folders only" is selected, and click "Finish".
Right-click the newly-added .jar file, and choose "Add to Build Path."

If you have an earlier release of Eclipse:

Outside of Eclipse, make a new directory (folder) and put jsr166.jar in it.
In Eclipse, create a new Java project. Choose "Create project from existing source" and choose the directory you created in the previous step.
In the project, choose Project → Properties from the menu. Under "Java Compiler" check "Enable project specific settings" and make sure the choice is Java 1.6.
In the list of files in the package viewer (over on the left), right-click on jsr166.jar and choose "Add to Build Path."

If using the command line, you need jsr166.jar in your build-path and you need to follow the instructions below for compiling and running.

A Main Class

Add a new class to your Eclipse project (or at the command-line create a file). Here is a simple file to cut-and-paste that uses the ForkJoin Framework, though not in a way that uses parallelism:

import java.util.concurrent.ForkJoinPool;
import java.util.concurrent.RecursiveTask;

class Incrementor extends RecursiveTask<Integer> {
	   int theNumber;
	   Incrementor(int x) {
	     theNumber = x;
	   }
	   public Integer compute() {
	     return theNumber + 1;
	   }
	}

public class WorkshopMain {
	public static ForkJoinPool fjPool = new ForkJoinPool();
	
	public static void main(String[] args) {
		int fortyTwo = (new Incrementor(41)).compute();
		System.out.println(fortyTwo);
	}
}

Compiling and running

There is an important step in here you cannot skip regardless of your IDE. As explained in detail below, you have to use the VM argument -Xbootclasspath/p:jsr166.jar written exactly like that (there's a hyphen, a slash, a colon, and a period).

In Eclipse (any version):

Under "Run, Configurations", create a new configuration for a Java application. Choose the appropriate main class, i.e., WorkshopMain if using the sample file above.
"Program Arguments" (the top box) is where normal command-line arguments go. We don't need any of those yet. "VM Arugments" (the bottom box) is where you need to enter -Xbootclasspath/p:jsr166.jar.

If using the command-line, you need jsr166.jar in your build path when you compile (javac) and you need this file and the -Xbootclasspath/p:jsr166.jar argument when you compile (javac) and run (java). You also need javac and java to be using version 1.6.

If all is well, the example program should print 42. Troubleshooting:

Getting a SecurityException when you run the program: you did not add the .jar file properly.
NoClassDefFoundError or something similar when you run the program: may mean that the 'VM Argument' isn't set correctly; it must be exactly -Xbootclasspath/p:jsr166.jar

Files for the Workshop Exercises

We will have time during the workshop for a couple fork-join exercises. The files support six total exercises, so you can continue after the workshop. This file describes the exercises; I'll provide a hardcopy at the workshop.

What you should do before the workshop:

Download WorkshopReductions.java and WorkshopMaps.java. If using Eclipse, add them to an Eclipse project.
You can also download reductionResults.txt and mapResults.txt, which contain the correct text output for all the exercises, but we won't have time for all the exercises and you may or may not even bother testing during the workshop.
Make sure you can run the two main methods. Remember you need Java 1.6 and the 'VM Argument' -Xbootclasspath/p:jsr166.jar. In Eclipse, I would make two 'Run Configurations', one with ReductionUtils as the main class and one with MapUtils as the main class.

If you have set everything up correctly, the files as provided will generate this output when run:

WorkshopReductions:

Testing Reductions

Test LeftmostStartsWith
test1 null
test2 null
test3 null
test4 null
test5 null

WorkshopMaps:

Testing Maps

Test RedactSWords
WRONG: did not redact SUCH0 at position 5042 now have SUCH0
test1 redacted 0 words
WRONG: did not redact S at position 18 now have S
test2 redacted 0 words
test3 redacted 0 words
WRONG: did not redact Salamander at position 99997 now have Salamander
test4 redacted 0 words
WRONG: did not redact Swan at position 5042 now have Swan
test5 redacted 0 words

Additional explanation (skimming/ignoring is fine)

Each file is self-contained, with everything you need to run ReductionUtils.main or MapUtils.main. But there are no naming conflicts between them, so they can but do not need to be in the same project. (They could even be combined into one file: Two files make them a little easier to navigate, but about 100 lines of testing code is duplicated in the two files to make this as simple as possible.)

These files may look large at first, but that's almost entirely because I provide code to generate five tests for each exercise. Pedagogically, I rarely provide tests to students, but I do here because there is no time in a workshop to write interesting test cases. Whether or not you choose to run and debug during the workshop or prefer just to work through "the idea" of the exercises is up to you.

Each file contains a "code template" (not in the C++ sense) that you can either copy-and-change or simply look at to make the boilerplate in the exercises much easier. Again, pedagogically, I choose not to provide students these templates, but rather have them discover the overwhelming similarity for different problems. Similarly, these patterns can be abstracted into library methods but I find it better to have students (at least first) write out the patterns several times.

The files do not include timing code for determining if parallelism is actually helping. That can be a natural and rewarding (or disappointing!) component of a project, but, as always, should come after understanding the algorithms.