Last Updated: March 5, 2011
by Dan Grossman
as part of his
teaching materials.
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.
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.