Running Java

This page is organized as follows:

Running Java on Departmental Linux Machines
Running Java and Eclipse on Your Home Machine
Troubleshooting

Running Java on Departmental Linux Machines

The departmental Linux machines are the recommended platforms for course work, but Java should run the same everywhere, so the choice is up to you.

This section is organized as follows:

Using the J2SDK tools
Working with Eclipse

Using the J2SDK tools under Linux

On the department Linux machines (popeye, etc.) the Java 2 Software Development Kit (J2SDK) is found in /usr/java/j2sdk/ (or some similar directory), which is in your PATH by default. (Thus you shouldn't have to do anything special to set this up.)

Java comes with several tools, the most commonly used of which are the compiler and the interpreter (or virtual machine). The compiler is called "javac" and the interpreter is called "java". Several other command line tools also come with Java, including "javadoc".

Information on running Java's tools is available in several ways on the department Linux systems. Probably the easiest way to get this information is to point your Web browser at the HTML index for the documentation in the release. On the departmental Linux systems this is /usr/java/j2sdk/docs/index.html. You can also read the manual page, for example for "javac", by typing at the Linux prompt:


          $ man javac

Note: In code examples, green text is program output, yellow bold text is user input, and cyan text is sample code.

To run the compiler you simply passed the names of the files to be compiled to it. For example:


          $ javac examples/StackTest.java

The compiler then produces a .class file, for example examples/StackTest.class.

To run the interpreter you first need to compile all of the Java source files for your application. Then you invoke the interpreter using the fully qualified name of the class containing the "main" method that you want to run. For example:


         $ java examples.StackTest

Return to Section Start

Setting the CLASSPATH under Linux

A common problem is that your CLASSPATH environment variable may not be set correctly. This variable must contain a path, which is a list of directories separated by colons (:), on Linux, and the directory containing the directory that names the package must appear in the CLASSPATH. For example, to run the interpreter as above on a program found in the package "examples", you must either:

have the current directory, ., or an empty component in your CLASSPATH, and the current directory must contain a subdirectory called "examples", or
have in your CLASSPATH the full path to a directory containing a subdirectory called "examples",
have in your CLASSPATH a path to a jar file containing the package called "examples".

Similar considerations apply to the compiler. See the documentation that comes with the J2SDK for for more information about setting the CLASSPATH. See also Java Glossary: classpath.

Return to Section Start

Setting the DISPLAY and using xhost under Linux

If you are running the interpreter across the network, that is it interpreter is executing on the different machines than the one whose screen you're looking at, then you also need to be sure to do two things:

Set and export the DISPLAY environment variable correctly. This especially must be done if your run of the Java interpreter has any kind of graphical output. Suppose you are sitting in front the screen for the machine "titus.cs.iastate.edu", but you are running Java remotely on the machine "popeye". You have open a shell window (e.g., running ssh) to "popeye". Then you should type into the shell window that is opened on the remote machine, popeye, (for the bash shell):
popeye$ export DISPLAY=titus.cs.iastate.edu:0
Note: In code examples, green text is program output, yellow bold text is user input, and cyan text is sample code.

If you are using tcsh instead of bash, then you should instead do:
popeye% setenv DISPLAY titus.cs.iastate.edu:0
See the manual page for the ssh command for more details.
popeye$ man ssh
Use the xhost command to tell the computer you are working on to give permission to the remote computer to open X windows displays on the computer you are working on. Again, suppose you are sitting in front the screen for the machine "titus", but you are running Java on the machine "popeye". Then you should type into a shell window on "titus" (not on popeye):
titus$ xhost +popeye.cs.iastate.edu
See the manual page for the xhost command for more details.

Return to Section Start

Working with Eclipse

The Eclipse editor is a free integrated development environment that works with Java. This is already installed on the department Linux systems and lives in /opt/eclipse. This should already be in your Linux PATH.

To start Eclipse on a department Linux machine, you just invoke it as follows.


          $ eclipse &

You need to have taken care of the DISPLAY and xhost settings for this to work.

When eclipse starts, look at the "Welcome" pane and click on the icon for the "Overview", "Tutorial", or "Samples" to learn how to use it.

In the "Overview", read the "Workbench basics" and "Java development" sections, but you can skip the other sections for now. You should start by reading the "Getting Started" Section, which you can do by clicking on the little plus sign (+) to the left of "Getting Started" in the table of contents, and then clicking on the topics underneath it. You'll also have to click on the little plus sign under the first subtopic underneath this, "Basic Tutorial" to expose the first thing to read ("The Workbench"). To move between sections, the most reliable way is to use the table of contents pane. Don't forget to click the little plus signs to the left of topics to see each of the subtopics.

If you find the overviw a bit dry, you may find the "Tutorial" more engaging. Try the "Java Development" tutorial that has you "Build a simple Java application".

Getting JUnit to Work with Eclipse under Linux

To get the JUnit tests to work under Eclipse, you have to have JUnit's jar file on the "Java Build Path" (which is the Eclipse version of the CLASSPATH). On the department Linux machines, JUnit is already downloaded. See Getting JUnit to Work with Eclipse on your Home Machine for some additional details on how to get this to work at home. On Linux, do this for an existing project in Eclipse

Download JUnit. On the the Linux machines it's already in /opt/junit.
Right click on the project name in the "Package Explorer Window", then select "Properties" (at the very bottom). Or select the project and the use the File menu's property item.
When you get the project properties, select the third item on the left, which is "Java Build Path".
Then select the "libraries" tab, and from the buttons on the right, click on "Add External JARs...".
Then browse until you can select the jar file junit.jar from the JUnit install, i.e., /opt/junit/junit.jar.
Click the bottom button "OK".

This should now make it so JUnit can be imported, and works in your project.

Return to Section Start

Return to top

Running Java and Eclipse on Your Home Machine

The Java J2SDK and the Eclipse editor will also be easy to use on your home machine. Eclipse works the same at home or at school. See the course resources web page for details on how to get these, and consult the installation notes that come with them.

Setting the PATH under Windows

Here's how to set the PATH evironment variable on Windows XP. First, open the start menu's control panel. Then select Performance and Maintenance, then (or directly) open the "System" tool, and then from the window, select the "Advanced" tab. At the bottom is a button for "Environment Variables"; click this, and there should be PATH (or something with different capitalization) in the "System Variables" list. On windows this is a semicolon-separated list of directories. Edit the listing to put the directory where you installed the Java executables in the list. For example, my PATH variable's value looks like the following.

.;d:\bin;d:\bat;c:\cygwin\usr\local\jdk1.4\bin;c:\ ...

In the above c:\cygwin\usr\local\jdk1.4 is the top directory of my Java installation. See also Java Glossary: environment.

Setting the CLASSPATH under Windows

A common problem is that your CLASSPATH environment variable may not be set correctly. This variable must contain a path, which is a list of directories separated by semicolons (;), on a windows machine, and the directory containing the directory that names the package must appear in the CLASSPATH. (This variable is set the same way that the PATH environment variable is.) For example, to run the interpreter as above on a program found in the package "examples", you must either:

have the current directory, ., or an empty component in your CLASSPATH, and the current directory must contain a subdirectory called "examples", or
have in your CLASSPATH the full path to a directory containing a subdirectory called "examples",
have in your CLASSPATH a path to a jar file containing the package called "examples".

Similar considerations apply to the compiler. See the documentation that comes with the J2SDK for for more information about setting the CLASSPATH. See also Java Glossary: classpath.

Getting JUnit to Work with Eclipse on your Home Machine

First you have to download JUnit from junit.org. Suppose download it and unzip it into C:\JUnit on a home machine.

Then see the section above on Getting JUnit to Work with Eclipse. However, when you add the external JAR file for JUnit, you will select the file C:\JUnit\junit.jar if your JUnit copy is installed in C:\JUnit.

Return to top

Troubleshooting Problems

For general help getting over the initial problems in getting Java to run, see the Getting Started section of the Java FAQ. See also Java Glossary: Getting Started.

Another good resource on getting going is the web page for the "getting started" lesson in the java tutorial. There is a set of detailed instructions for working with Java under Microsoft Windows. and another for Unix and Linux (but don't use pico, use emacs!), and yet another for Mac OS.

Yet another good reference, this time for using Eclipse, is the Basics of Java Development website.

Eclipse Install Failure to Find Java

To install and run Eclipse, you first have to install Java on your machine.

If, when you try to run Eclipse, you get a message like the following:

"A Java Runtime Environment(JRE) or Java Development(JDK) must be available in order to run Eclipse. No Java virtual machine was found after searching the following locations: ... 'javaw.exe' in your current PATH."

Then the problem is that either your installation of Java is incomplete, or that your PATH environment variable does not contain the bin directory for your Java installation, or that you don't have permission to execute the virtual machine (java or javaw) in your java installation.

See also the Getting Started section of the Eclipse FAQ.

Reading Error Messages (Exception Backtraces)

Here's the most common error that you'll see in a Java program.


    $ java Test

    java.lang.NullPointerException

    at Test.main(Test.java:5)

    Exception in thread "main"

What this means is that your program encountered an unhandled exception, named java.lang.NullPointerException. The exception was encountered at line 5 of the file Test.java, inside the method named "Test.main". Execution terminated because of this exception in the thread "main". In general, there may be a long trace of stack frames instead of the single one as shown above (see the example below). The crucial information is to pick out (a) the particular exception that happened, and (b) where it happened. This particular, very common exception is due to the use of a variable that had the value null. In the example, my code was x.equals(x);, and x had the value "null".

Return to Section Start

Can't Connect to X11 Server

When you first start working with the Java interpreter for a program with graphical output, you may see an error like the following.


$ java PinBallGame

Exception in thread "main" java.lang.InternalError: Can't connect to X11 window server using ':0.0' as the value of the DISPLAY variable.

        at sun.awt.X11GraphicsEnvironment.initDisplay(Native Method)

        at sun.awt.X11GraphicsEnvironment.<clinit>(X11GraphicsEnvironment.java:126)

        at java.lang.Class.forName0(Native Method)

        at java.lang.Class.forName(Class.java:130)

        at java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment(GraphicsEnvironment.java:62)

        at java.awt.Window.init(Window.java:223)

        at java.awt.Window.<init>(Window.java:267)

        at java.awt.Frame.<init>(Frame.java:398)

        at java.awt.Frame.<init>(Frame.java:363)

        at PinBallGame.<init>(PinBallGame.java:54)

        at PinBallGame.main(PinBallGame.java:24)

This looks rather nasty, but take a closer look. On the first line above, you can see that there is the error message: Can't connect to X11 window server using ':0.0' as the value of the DISPLAY variable. This is your clue that the problem has to do with the X window system. It may be that the setting of your DISPLAY environment is wrong, or it may be that the relevant xhost command needs to be issued to let the remote system put windows on your display. This is something you need to fix if you are running the interpreter from a Unix or Linux machine. See the section on setting DISPLAY and xhost.

Return to Section Start

NoClassDefFoundError

If you get java.lang.NoClassDefFoundError when runing the Java interpreter (java), it means that either (a) you gave the name of the class wrong, or that (b) you have your CLASSPATH set wrong. See the sections above for setting the CLASSPATH on Linux or Windows.

One of the ways in which the name of the class can be wrong is to have the wrong case. Java is case-sensitive, but on a Windows machine, filenames are not case-sensitive. Therefore the Java interpreter might be able to find the class file that contains the wrong class name. Consider the following execution.


$ javac ClassesStartWithCaps.java

$ java ClassesStartWithCaps

hi

$ java classesstartwithcaps

java.lang.NoClassDefFoundError: classesstartwithcaps (wrong name: ClassesStartWithCaps)

at java.lang.ClassLoader.defineClass0(Native Method)

at java.lang.ClassLoader.defineClass(ClassLoader.java:502)

at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:123)

at java.net.URLClassLoader.defineClass(URLClassLoader.java:250)

at java.net.URLClassLoader.access$100(URLClassLoader.java:54)

at java.net.URLClassLoader$1.run(URLClassLoader.java:193)

at java.security.AccessController.doPrivileged(Native Method)

at java.net.URLClassLoader.findClass(URLClassLoader.java:186)

at java.lang.ClassLoader.loadClass(ClassLoader.java:299)

at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:265)

at java.lang.ClassLoader.loadClass(ClassLoader.java:255)

at java.lang.ClassLoader.loadClassInternal(ClassLoader.java:315)

Exception in thread "main"

The first of these works, because the class name is given correctly with the proper cases of the letters. The second one does not work because the class name is given incorrectly.

Return to Section Start

Return to top

Last modified Tuesday, August 31, 2004.

This web page is for the Fall 2003 offering of Com S 541 at Iowa State University. The details of this course are subject to change as experience dictates. You will be informed of any changes. Please direct any comments or questions to Gary T. Leavens at leavens@cs-DOT-iastate-DOT-edu (after replacing -DOT- with `.').